home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / relnotes / WorkShop / ch5.z / ch5
Text File  |  2001-04-17  |  121KB  |  2,905 lines
  1.  
  2.  
  3.  
  4.                                   - 1 -
  5.  
  6.  
  7.  
  8.        5.  _K_n_o_w_n__P_r_o_b_l_e_m_s__a_n_d__W_o_r_k_a_r_o_u_n_d_s
  9.  
  10.        5.1  _W_o_r_k_S_h_o_p__D_e_b_u_g_g_e_r
  11.  
  12.           +o The 2.6.5 version of the WorkShop debugger has problems
  13.             evaluating references to class data members and the
  14.             "this" pointer in C++ programs compiled with the 7.1
  15.             and 7.0 versions of the C++ compiler.
  16.  
  17.             Workaround: You can recompile your code using the 7.2
  18.             version of the compiler.  These expressions work
  19.             correctly with the output of the 7.2 compiler.  If you
  20.             must debug 7.1 or 7.0 generated programs or DSOs, add
  21.             the following line to your .Xdefaults file:
  22.  
  23.             ****uuuusssseeeeOOOOllllddddEEEExxxxpppprrrrEEEEvvvvaaaallll:::: ttttrrrruuuueeee
  24.             ****UUUUsssseeeeOOOOllllddddEEEExxxxpppprrrrEEEEvvvvaaaallll:::: ttttrrrruuuueeee
  25.  
  26.             This will allow you to reference class data members,
  27.             but you will have to reference them as "this->member".
  28.  
  29.  
  30.           +o There is a limitation in the specification of the type
  31.             for a C++ exception trap.  The determination as to
  32.             whether a particular type has been thrown does not take
  33.             into account typedefs.  For example, given the type
  34.             definition:
  35.  
  36.             ttttyyyyppppeeeeddddeeeeffff cccchhhhaaaarrrr ****SSSSttttrrrriiiinnnngggg;;;;
  37.  
  38.             setting the breakpoint:
  39.  
  40.             ssssttttoooopppp eeeexxxxcccceeeeppppttttiiiioooonnnn SSSSttttrrrriiiinnnngggg
  41.  
  42.             would have no effect.
  43.  
  44.             Workaround:  Use the base type specified in the typedef
  45.             when setting the breakpoint.
  46.  
  47.           +o After using cvd's Trap menu to change the setting of
  48.             Group Trap Default or Stop All Default, after an
  49.             extended period a dialog box may display the message
  50.             "Error: No debugger available to set trap modes".  This
  51.             can be ignored.
  52.  
  53.           +o When parameter declaration inside a subroutine uses (*)
  54.             type of syntax i.e.  character *(*), cvd will not be
  55.             able to display its content correctly. (Incident
  56.             #178191)
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.                                   - 2 -
  71.  
  72.  
  73.  
  74.           +o Memory leak experiments might fail to unwind the stack
  75.             when particular functions are found in the stack (such
  76.             as usinit() from IRIX 6.2 libc or some libgl
  77.             functions).
  78.  
  79.             Workaround:  There is no good workaround for this
  80.             problem.
  81.  
  82.           +o The ability to unwind the call stack using the Call
  83.             Stack View does not work reliably. Stack traces will be
  84.             incomplete when stopped in a signal handler of a 4.X
  85.             binary running on a 5.X or a 6.X system. Returning from
  86.             the signal handler using "step into", "step over" and
  87.             "return" will not work correctly.  Similarly,
  88.             registering a signal through sigaction call with the
  89.             SA_SIGINFO flag set may cause incorrect stack traces
  90.             when stopped in the signal handler. (Incident #215151)
  91.  
  92.             Workaround:  There is no good workaround for this
  93.             problem.
  94.  
  95.           +o On 5.X, 6.0, and 6.1 systems the debugger has trouble
  96.             detecting mismatches between an executable and core
  97.             file (the problem is resolved on 6.2 systems).  If this
  98.             problem occurs, you are likely to receive an incorrect
  99.             stack trace without any warning that the core file may
  100.             not be based on the given executable. (Incident
  101.             #186347)
  102.  
  103.           +o The views that do expression evaluation, Expression
  104.             View, the Evaluate Expression dialog box, Structure
  105.             Browser, Variable Browser, Array Visualizer, and the
  106.             Debugger command line cannot yet evaluate:
  107.  
  108.                - long double (C/C++) and unsigned variants
  109.  
  110.                - real * 16 (Fortran) and unsigned variants
  111.  
  112.                - complex *32 (Fortran) and unsigned variants
  113.  
  114.             Evaluation of these types is not available at this
  115.             time.  (Incident #206313)
  116.  
  117.           +o Making an interactive function call when the target
  118.             process is sleeping in a system call will cause the
  119.             target to fault. (Incident #223601)
  120.  
  121.           +o WorkShop does not accommodate text editors other than
  122.             Source View very well.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.                                   - 3 -
  137.  
  138.  
  139.  
  140.             Workaround:  Set the _e_d_i_t_o_r_C_o_m_m_a_n_d resource in the
  141.             _a_p_p-_d_e_f_a_u_l_t_s file to your desired editor.  For example,
  142.             set _e_d_i_t_o_r_C_o_m_m_a_n_d to _w_s_h -_c _v_i +%_d to run _v_i in a _w_s_h
  143.             window. You also need to set *_u_s_e_T_o_o_l_T_a_l_k to _F_a_l_s_e.
  144.  
  145.           +o The request to kill a process which has spawned child
  146.             processes (through _f_o_r_k(), _s_p_r_o_c(), or _s_p_r_o_c_s_p()),
  147.             followed by exiting _c_v_d, may not properly terminate the
  148.             descendant processes. The descendant processes may
  149.             continue to run after _c_v_d has exited.  (Incident
  150.             #206273)
  151.  
  152.             Workaround:  Kill all of the process group members with
  153.             the Multiprocess View as opposed to using the Main
  154.             View.  If any of the descendant processes were created
  155.             through a _f_o_r_k(), you will have had to direct the
  156.             Multiprocess View to attach to _f_o_r_k()ed process (see
  157.             ``Config: Preferences'' in the Multiprocess View).
  158.  
  159.           +o The Multiprocess View is known to occasionally not
  160.             display all process group members which _c_v_d is attached
  161.             to.  One condition where this problem occurs is when
  162.             the list of processes shown by the Multiprocess View is
  163.             frequently changing in a short span of time (for
  164.             example, processes are _f_o_r_k()ed which _e_x_e_c() and exit
  165.             shortly after they start).  (Incident #244782)
  166.  
  167.             Workaround:  Use of Stop in the Multiprocess View will
  168.             cause _c_v_d to stop all process group members and the
  169.             display should change to correctly list all processes.
  170.  
  171.           +o When _c_v_d is brought up on one member of a running
  172.             shared process group (see _s_p_r_o_c(2)), _c_v_d does not
  173.             identify and attach to all of the other processes which
  174.             are members of the shared process group. If you start
  175.             up the Multiprocess View you will only see the process
  176.             you started _c_v_d on.  The correct behavior from the
  177.             Multiprocess View would be to display all members of
  178.             the shared process group.  (Incident #179940)
  179.  
  180.             Workaround:  Use ``Process: Add'' in the Multiprocess
  181.             View to manually add each member of the shared process
  182.             group to the _c_v_d process group display by Multiprocess
  183.             View.
  184.  
  185.           +o Attempts to add a process which has been removed from
  186.             Multiprocess View may fail or lead to an abort of the
  187.             Multiprocess View.  (Incident #168934)
  188.  
  189.           +o Disassembly View sometimes has problems when two or
  190.             more DSOs have overlapping text.  In such cases,
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.                                   - 4 -
  203.  
  204.  
  205.  
  206.             Disassembly View displays only one of the DSOs from the
  207.             set whose text overlaps. This can happen to users who
  208.             are building their own DSOs.  Unfortunately _c_v_d does
  209.             not warn the user when this type of conflict occurs.
  210.             (Incident #204024)
  211.  
  212.           +o On attempting to locate the DSOs used by an executable,
  213.             _c_v_d uses the shell environment in which _c_v_d was
  214.             started, as opposed to the shell environment within the
  215.             Execution View.  This means that the value of
  216.             environment variables like LLLLDDDD____LLLLIIIIBBBBRRRRAAAARRRRYYYY____PPPPAAAATTTTHHHH which are
  217.             used by _c_v_d may not match the values in the shell where
  218.             the executable will be run.  When _c_v_d is using the
  219.             wrong values for environment variables like
  220.             LLLLDDDD____LLLLIIIIBBBBRRRRAAAARRRRYYYY____PPPPAAAATTTTHHHH, it may have trouble finding all of the
  221.             appropriate DSO symbol tables.  When _c_v_d has trouble
  222.             finding DSOs used by an executable it will display the
  223.             Library Search Path dialog to call attention to the
  224.             DSOs which could not be found. (Incidents #224125,
  225.             #236651)
  226.  
  227.             Workaround:  Use ``Admin: Library Search Path ...'' to
  228.             examine and set environment variables like
  229.             LLLLDDDD____LLLLIIIIBBBBRRRRAAAARRRRYYYY____PPPPAAAATTTTHHHH which control the identification of
  230.             DSOs.
  231.  
  232.           +o Watchpoints in _c_v_d may be defined with an address and
  233.             size or an expression.  If you attempt to watch an
  234.             expression which resides on the stack (for example, a
  235.             local variable) _c_v_d will not allow definition of the
  236.             trap.  _c_v_d will only watch expressions whose location
  237.             is within a mapping other than the stack.  (Incident
  238.             #197233)
  239.  
  240.             Workaround:  If you want to watch an expression which
  241.             resides on the stack, use the expression evaluator to
  242.             find the address of the expression and create the
  243.             watchpoint using the address.  Once the expression is
  244.             deallocated, the watchpoint should be removed to avoid
  245.             any confusion when the stack address is reused for some
  246.             other purpose later on in the execution.
  247.  
  248.           +o Process group watchpoints involving expressions are not
  249.             supported well.  If you create a watchpoint with a
  250.             command like ppppggggrrrrpppp wwwwaaaattttcccchhhh <<<<eeeexxxxpppprrrreeeessssssssiiiioooonnnn>>>>, the expression is
  251.             only evaluated once on one of the process group
  252.             members.  The evaluation is used to determine the
  253.             address and size of the watchpoint, and address and
  254.             size is used to create a watchpoint on each process
  255.             group member.  This will only work correctly if the
  256.             address and size of the expression is the same for each
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.                                   - 5 -
  269.  
  270.  
  271.  
  272.             process group member.  There is no workaround known for
  273.             this problem.  (Incident #143367)
  274.  
  275.           +o The Trap Manager fails to properly define watchpoints
  276.             on 64-bit addresses.  The address typed in the
  277.             ``Trap:'' field is corrupted and either a watchpoint is
  278.             created on the wrong address or an invalid address
  279.             error is reported (_W_a_t_c_h_p_o_i_n_t _a_d_d_r_e_s_s _r_a_n_g_e _i_n_c_l_u_d_e_s _a_n
  280.             _i_n_v_a_l_i_d _v_i_r_t_u_a_l _a_d_d_r_e_s_s.).  (Incident #235635)
  281.  
  282.             Workaround: The command line interface panel in the _c_v_d
  283.             Main View can be used in place of the Trap Manager to
  284.             enter the watchpoint command.
  285.  
  286.           +o _c_v_d does not have support for weak symbols (see
  287.             Appendix A of the _C _L_a_n_g_u_a_g_e _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l).  _c_v_d
  288.             will not recognize the weak symbol name.  For example,
  289.             _c_v_d will not accept a request to trap on entry to
  290.             dlopen.  (Incident #181409)
  291.  
  292.             Workaround:  Use the "strong" symbol name in place of
  293.             the weak one.  Many weak symbols defined in libc have
  294.             corresponding "strong" symbol names which are the weak
  295.             name with a ``_'' prepended onto the front.  For
  296.             example, the "strong" symbol name for dlopen is
  297.             _dlopen.
  298.  
  299.           +o A write watchpoint may fail to fire when the write
  300.             occurs within a syscall.  For example, a write
  301.             watchpoint on one word within a buffer written by read
  302.             may fail to fire.
  303.  
  304.             Workaround:  Define the watchpoint to cover the entire
  305.             data structure as opposed to a subset of the structure.
  306.             For example, define the watchpoint over the entire
  307.             buffer being handed to read as opposed to a single
  308.             word.
  309.  
  310.           +o An attempt to step into the first call to an external
  311.             function will behave like a step over.  The first call
  312.             to an external function invokes rld to resolve the
  313.             function address.  When this occurs the request to step
  314.             into the call will look like a step over to the user.
  315.             (Incident #147302)
  316.  
  317.             Workaround: Either set the environment variable
  318.             _L_D__B_I_N_D__N_O_W to 1 in the Execution View prior to running
  319.             the program (see _r_l_d(1)) or use function entry
  320.             breakpoints.
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.                                   - 6 -
  335.  
  336.  
  337.  
  338.           +o Traps placed within a parallel Fortran DO loop, created
  339.             with the C$DOACROSS compiler directive, fail to work
  340.             correctly.  Although the traps appear to be placed
  341.             correctly on 6.0 systems, the process will not stop on
  342.             the traps.  On 5.3 systems the traps cannot be placed
  343.             within the loop at all.  (Incident #20818)
  344.  
  345.             Workaround:  On a 6.0 system _d_b_x can be used
  346.             successfully to place traps within the loop.
  347.  
  348.           +o The Fortran intrinsics _c_h_a_r, _z_e_x_t, _s_e_c_o_n_d_s, _m_a_l_l_o_c, and
  349.             _e_p are not supported.  (Incident #206293)
  350.  
  351.           +o The debugger does not understand external or intrinsic
  352.             statements in the Fortran program.  If the program has
  353.             a function by the same name as an intrinsic function,
  354.             evaluating an expression involving that function will
  355.             always cause the program function to be called.
  356.  
  357.           +o Some of the intrinsics (_s_q_r_t, _e_x_p, _l_o_g, _l_o_g_1_0, _s_i_n,
  358.             _c_o_s, _t_a_n, _a_s_i_n, _a_c_o_s, _a_t_a_n, _s_i_n_h, _c_o_s_h, _t_a_n_h) do not
  359.             give the correct results when the debugged executable
  360.             is linked with _l_i_b_m._s_o.  This is because of entry
  361.             points with similar names in _l_i_b_m._s_o.
  362.  
  363.             Workaround: Use a specific intrinsic name.  For
  364.             example, _s_i_n(_r_1) where _r_1 is real will produce
  365.             incorrect results.  On the otherhand, _d_s_i_n(_d_f_l_o_a_t(_r_1))
  366.             will give correct results, with the results being a
  367.             _r_e_a_l *_8 quantity.
  368.  
  369.           +o Stopping in the entry prologue of a function (before
  370.             the first user statement) in a Fortran program and
  371.             evaluating an expression that involves an adjustable
  372.             array or displaying an adjustable array in the Array
  373.             Visualizer will not work correctly.  (Incident #206264)
  374.  
  375.             Workaround: Step to the first user statement and
  376.             evaluate the expression.
  377.  
  378.           +o When stopped in a Fortran function/subprogram that has
  379.             alternate entry points, the debugger will not list all
  380.             the arguments of the subprogram and their values
  381.             correctly.  (Incident #164327)
  382.  
  383.           +o For global lookups, _c_v_d acts as though all DSOs are
  384.             built ----BBBB ssssyyyymmmmbbbboooolllliiiicccc.  If a process is stopped within a
  385.             DSO and the user asks _c_v_d to lookup a global variable
  386.             or function, _c_v_d will always look within the DSO before
  387.             it considers the main program or any other DSO.  In
  388.             effect, _c_v_d is acting as if each DSO has been built
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.                                   - 7 -
  401.  
  402.  
  403.  
  404.             with ----BBBB ssssyyyymmmmbbbboooolllliiiicccc.  (Incidents #173343)
  405.  
  406.           +o Interactive calls to inline member functions of C++
  407.             classes is not supported.
  408.  
  409.           +o There is no support for C++ overloaded operators in the
  410.             expression evaluator.  (Incident #203968)
  411.  
  412.           +o The debugger does not have full support for C++
  413.             templates.  However, the user can stop in template code
  414.             and print the ``this'' pointer.  (Incidents #140313,
  415.             #140316, #222352)
  416.  
  417.           +o The display format for describing an array pointer
  418.             types is incorrect.  For example, an array of
  419.             double(*)[2] is expressed as double[]*.
  420.  
  421.           +o Elements of Fortran arrays with more than 6 dimensions
  422.             (or 5 dimensions, if the element type is character
  423.             string) cannot be referenced.
  424.  
  425.           +o C++ objects containing virtual base classes do not
  426.             display correctly in the expression evaluator.
  427.             (Incident #190170)
  428.  
  429.           +o _c_v_p_c_s can stack trace through assembler alternate entry
  430.             functions only when they are at the same address as the
  431.             main entry point.  Assembler functions with arbitrary
  432.             alternate entry points will produce incorrect stack
  433.             trace.
  434.  
  435.           +o When the Trap Manager is invoked, traps are
  436.             automatically loaded from the ._c_v_T_r_a_p_M_g_r file if one
  437.             exists.  However, these traps are reloaded if the Trap
  438.             Manager is closed and restarted.  (Incident #79217)
  439.  
  440.             Workaround: The Trap Manager should either be left
  441.             running or the default traps should be stored in a
  442.             different file and reloaded manually when desired.
  443.  
  444.           +o In general, when a write watchpoint fires, the write is
  445.             simulated by the debugger to show the new value before
  446.             any trap conditional is evaluated.  The four exceptions
  447.             for this case are the SC, SCD, SDL, and SDR
  448.             instructions.  (Incident #250036)
  449.  
  450.           +o A kernel bug prevents watchpoints from firing reliably
  451.             for members of share process groups (such as Power
  452.             Fortran or Power C programs).  Watchpoints work
  453.             reliably for non-shared text and data segments in each
  454.             individual process.
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.                                   - 8 -
  467.  
  468.  
  469.  
  470.           +o If you stop a process through job control, the debugger
  471.             may not display an accurate status of the process, and
  472.             process control requests do not take effect until the
  473.             process is resumed through job control.  A process is
  474.             stopped through job control with <Ctrl-Z> from the
  475.             shell or when it receives one of the signals: SIGSTOP,
  476.             SIGTSTP, SIGTTIN, and SIGTTOU.  A process is resumed
  477.             through job control with _f_g and _b_g from the shell or
  478.             when it receives the signal SIGCONT.  If a running
  479.             process is stopped through job control, the debugger
  480.             continues to show that the process is running.  When
  481.             attaching to a process stopped through job control, the
  482.             debugger shows that the process is stopped.  (Incident
  483.             #167693)
  484.  
  485.           +o For instrumented executables (used for performance
  486.             analysis), stack frame unwinding may be incomplete when
  487.             stopped in a signal handler; the unwinding may stop
  488.             prematurely after the ``_sigtramp'' frame.  (Incident
  489.             #71307)
  490.  
  491.             Workaround: A full stack trace may be maintained by
  492.             returning past the ``_sigtramp'' frame.
  493.  
  494.           +o The demo program _j_e_l_l_o cannot be built as described in
  495.             the tutorial without the library /_u_s_r/_l_i_b/_l_i_b_g_l._s_o.
  496.  
  497.             Workaround:  This library should be installed when IRIX
  498.             is installed (eoe1.sw.gfx_lib subsystem).
  499.  
  500.           +o Processes that use the blocking capabilities as
  501.             provided by _b_l_o_c_k_p_r_o_c(2) may not terminate as expected
  502.             upon completion of a debug session.  Such processes are
  503.             left in a blocked state with a SIGKILL pending.
  504.  
  505.             Workaround:  These processes can be terminated with
  506.             _k_i_l_l(1).
  507.  
  508.           +o The modification of an inactive trap will cause the
  509.             trap to become active.  You will have to toggle the
  510.             active button next to the trap description in order to
  511.             deactivate the trap.  (Incident #190278)
  512.  
  513.           +o There is a case where the path remapping component of
  514.             WorkShop will find the wrong file.  When _c_v_d is stopped
  515.             and started multiple times, and ``Admin:Exit'' was used
  516.             to exit _c_v_d, the path remapping component will retain
  517.             entries in its Substitution Set from each debugging
  518.             session (see ``Admin:Project:Remap Paths...'').  The
  519.             path remapping component of _c_v_d is implemented as a
  520.             separate process and the ``.'' entry in the
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.                                   - 9 -
  533.  
  534.  
  535.  
  536.             Substitution Set refers to the directory in which the
  537.             process was started, typically the directory were the
  538.             first _c_v_d was started.
  539.  
  540.             Workaround: Use ``Admin:Project:Exit'' in place of
  541.             ``Admin:Exit''.  This will force the path remapping
  542.             process to terminate on each exit of _c_v_d.
  543.  
  544.           +o By default the debugger will not attach to a _f_o_r_k()ed
  545.             process unless the fork occurs during an interactive
  546.             function call.  If you have used the Multiprocess View
  547.             preferences dialog to prevent a forked child from being
  548.             resumed, and you make an interactive function call will
  549.             leads to a call on fork, the child process will be left
  550.             stopped on exit from fork.  You must now use the
  551.             Multiprocess View to resume the child process.
  552.             (Incident #190308)
  553.  
  554.           +o _c_v_d may fail to recognize that a DSO source file is
  555.             newer than the DSO.  Although such a source file may be
  556.             the wrong version for the code which is executing, _c_v_d
  557.             will not issue a warning. The source of the problem is
  558.             that _c_v_d is always comparing time of last modification
  559.             for the source file against the executable when it
  560.             should be comparing against the DSO.  (Incident
  561.             #181297)
  562.  
  563.           +o Fortran COMMON block members that are at an offset
  564.             greater than 8 Megabytes from the start of the common
  565.             block will not be evaluated correctly in an expression.
  566.  
  567.           +o When using the Switch Process dialog to attach to an
  568.             existing process, don't attach to one of the CaseVision
  569.             or WorkShop processes (e.g. _c_v_p_a_t_h_R_e_m_a_p, _c_v_m_a_i_n) or the
  570.             environment may hang. Should this happen, kill the
  571.             _c_v_m_a_i_n process and start over.
  572.  
  573.           +o Occasionally, _c_v_m_a_i_n will dump core at startup if you
  574.             have an executable with a mismatched core file and your
  575.             NetLS license is within 90 days of expiring.  If this
  576.             happens, restart _c_v_d.
  577.  
  578.           +o The request to print the content of a very large data
  579.             structure (such as an array) from within the main
  580.             window's command line interface panel may lead to an
  581.             abort of _c_v_d.  (Incident #227980)
  582.  
  583.             Workaround:  The Array Browser may be used to display
  584.             very large arrays.
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.                                   - 10 -
  599.  
  600.  
  601.  
  602.           +o The main window's command line interface panel will
  603.             only display the first 100 elements of an array.  There
  604.             is no way to change this behavior.  (Incident #250028)
  605.  
  606.             Workaround:  The best way to examine an array is the
  607.             Array Browser.
  608.  
  609.           +o With an executable built with the DCC compiler,
  610.             attempts at retrieving symbolic information about
  611.             _o_s_t_r_e_a_m may lead to an abort of _c_v_p_c_s.  Entering the
  612.             command wwwwhhhhaaaattttiiiissss oooossssttttrrrreeeeaaaammmm in _c_v_d will lead to such an
  613.             abort.  (Incident #239838)
  614.  
  615.           +o The _c_v_p_c_s component of _c_v_d is known to abort on very
  616.             large COFF format executables. (Incident #244495)
  617.  
  618.           +o The command line interface panel in the _c_v_d Main View
  619.             may fail to evaluate expressions when the process is
  620.             stopped and the language of the current context is
  621.             Assembler. (Incident #246294)
  622.  
  623.             Workaround: The Expression View can be used in place of
  624.             the command line interface panel.
  625.  
  626.           +o After a process has stopped, an expression value may
  627.             become invalid due to evaluation of another expression
  628.             or use of debugger commands which can lead to
  629.             modification of expression values.  An example would be
  630.             the value of a variable displayed in Expression View
  631.             which is not recalculated after the variable is updated
  632.             with the _a_s_s_i_g_n command in the command line interface
  633.             panel.  (Incident #247050)
  634.  
  635.             Workaround: Force the value of the expression to be
  636.             recalculated by retyping the expression.
  637.  
  638.           +o The Array Visualizer will no longer implicitly use _t_h_i_s
  639.             on a C++ program.  When attempting to display the
  640.             member of a class you will have to explicitly include
  641.             _t_h_i_s-> along with the name of the member.  (Incident
  642.             #248882)
  643.  
  644.           +o Use of the division, and modulus operators in the
  645.             ``Indexing Expression:'' field of the Array Visualizer
  646.             may not work correctly on 64-bit executables.
  647.             (Incident #249262)
  648.  
  649.           +o On startup _c_v_d connects to an underlying process
  650.             control server.  Due to a change in WorkShop 2.4, when
  651.             _c_v_d is using a version of the communication protocol
  652.             which is incompatible with the version used by the
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.                                   - 11 -
  665.  
  666.  
  667.  
  668.             server it can no longer recognize the condition and
  669.             report the incompatible version numbers.  As in
  670.             previous versions of WorkShop, _c_v_d will exit, but it
  671.             will no longer report the mismatch of communication
  672.             protocol versions. (Incident #233399)
  673.  
  674.           +o _c_v_d may not list all the member functions of a class
  675.             correctly when the class and its member functions are
  676.             built into a separate DSO.  (Incident #249733)
  677.  
  678.           +o If the application uses the isolate process (or CPU
  679.             pinning) feature of IRIX, the thread pinned to a
  680.             specific CPU cannot be debugged.  The isolate process
  681.             feature is accessed by a call to _s_y_s_m_p(_M_P__I_S_O_L_A_T_E).
  682.             (Incident #216158)
  683.  
  684.             Workaround: Disable calls to _s_y_s_m_p(_M_P__I_S_O_L_A_T_E) to
  685.             enable debugging.
  686.  
  687.           +o Occasionally, path remapping will cease to function
  688.             properly: new entries in the list will not take
  689.             immediate effect, yet if you exit and restart _c_v_d, they
  690.             will apply. (Incident #247133)
  691.  
  692.             Workaround: Exit _c_v_d and kkkkiiiillllllllaaaallllllll ttttttttsssseeeessssssssiiiioooonnnn.
  693.  
  694.           +o _c_v_d cannot evaluate expressions involving local classes
  695.             (classes that are defined inside of a function).
  696.             (Incident #212268)
  697.  
  698.           +o The Query menu within _c_v_d will fail to operate
  699.             correctly if _c_v_d was attached to a running process (ccccvvvvdddd
  700.             ----ppppiiiidddd ............)  or if _c_v_s_t_a_t_i_c is started by hand (``Admin:
  701.             Launch Tool -> Static Analyzer'').   (Incident #238595)
  702.  
  703.           +o A trap at the closing brace of a C/C++ function may not
  704.             be defined properly.  This is known to occur when the
  705.             last statement of the function is a return statement.
  706.             When this problem occurs the trap is defined on a
  707.             source line following the closing brace, typically the
  708.             opening brace of the next function.
  709.  
  710.             Workaround: Place the trap on the source line
  711.             containing the return statement as opposed to the line
  712.             containing the closing brace.   (Incident #277136)
  713.  
  714.           +o _c_v_d may close file descriptors it should leave open in
  715.             the _r_u_n command.  All file descriptors at 3 and above
  716.             are closed by _c_v_d.   (Incident #277295)
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.                                   - 12 -
  731.  
  732.  
  733.  
  734.           +o The Structure Browser is known to abort when asked to
  735.             display more than 100 elements of a linked list.
  736.             (Incident #278140)
  737.  
  738.           +o The _c_v_p_c_s component of _c_v_d is known to occasionally
  739.             abort on erroneous expression evaluation requests from
  740.             the one-time expression evaluation component of _c_v_d.
  741.             (Incident #282160)
  742.  
  743.           +o Evaluation of a C++ expression which contains a
  744.             variable whose name is the same as that of a structure
  745.             may lead to an erroneous error.   (Incident #286949)
  746.  
  747.           +o When stopped at the entry to a function compiled N32 or
  748.             64-bit the debugger's Call Stack View does not always
  749.             report the correct arguments to that function.  Usually
  750.             the arguments will be correct after stepping one or
  751.             more lines into the function.
  752.  
  753.           +o Under some conditions, on some R5K Indy and O2
  754.             machines, a hardware problem may cause traps to not
  755.             fire the first time they are encountered.  Rerun often
  756.             works around the problem (Incident #439770).
  757.  
  758.        5.1.1  _D_e_b_u_g_g_i_n_g__6_4_-_b_i_t__a_n_d__N_3_2__C_+_+__p_r_o_g_r_a_m_s  This section
  759.        discusses problems that are unique to debugging 64-bit and
  760.        N32 C++ programs.  (The problems discussed in the previous
  761.        section may also apply to 64-bit and N32 C++ debugging.)
  762.  
  763.        The first two problems on the following list are limitations
  764.        of this release of the debugger; they will be fixed in a
  765.        future release.  The remaining problems will be fixed by a
  766.        future release of the C++ compiler.
  767.  
  768.           +o Interactive function calls to member functions cannot
  769.             be performed through objects of the class using the ->
  770.             or . access operators.
  771.  
  772.             Workaround: Perform the interactive function call using
  773.             the class-qualified name.  In such a call, the _t_h_i_s
  774.             parameter must be passed explicitly.
  775.  
  776.             ccccllllaaaassssssss nnnnooooddddeeee {{{{
  777.                 nnnnooooddddeeee ****____rrrriiiigggghhhhtttt;;;;
  778.                 nnnnooooddddeeee ****____lllleeeefffftttt;;;;
  779.             ppppuuuubbbblllliiiicccc::::
  780.                 nnnnooooddddeeee(((())));;;;
  781.                 nnnnooooddddeeee**** rrrriiiigggghhhhtttt(((())));;;;
  782.                 nnnnooooddddeeee**** lllleeeefffftttt(((())));;;;
  783.             }}}};;;;
  784.             nnnnooooddddeeee ****nnnn;;;;
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.                                   - 13 -
  797.  
  798.  
  799.  
  800.             In this example, the member functions cannot be called
  801.             as _n->_r_i_g_h_t() or _n->_l_e_f_t().  Instead, they must be
  802.             called as _n_o_d_e::_r_i_g_h_t(_n) or _n_o_d_e::_l_e_f_t(_n).
  803.  
  804.           +o The _t_h_i_s parameter is not explicitly dereferenced in
  805.             member functions.
  806.  
  807.             Workaround: Access members of the _t_h_i_s parameter in a
  808.             member function by using the _t_h_i_s-> accessor.
  809.  
  810.           +o There is no debugging output for anonymous unions
  811.             declared in a block. (Incident 236926)
  812.  
  813.           +o Static data members cannot be accessed using the -> or
  814.             . access operators. (Incident 237006)
  815.  
  816.             Workaround: Access static data members using the
  817.             class-qualified name.
  818.  
  819.           +o Static member functions cannot be accessed using the ->
  820.             or . access operators, or by using the class-qualified
  821.             name. (Incident 237029)
  822.  
  823.             Workaround: Access static member functions using only
  824.             the name of the member function; do not use the class-
  825.             qualified name.
  826.  
  827.           +o Nested C++ classes appear as global classes.  (Incident
  828.             242800)
  829.  
  830.           +o The tag for nested C++ structures is incorrect.
  831.             Instead of the correct tag name, the C++ mangled name
  832.             is used. (Incident 244522)
  833.  
  834.           +o The type is incorrect for point-to-member variables.
  835.             Instead of having the correct pointer-to-member type,
  836.             these variables have the type of the member to which
  837.             they're pointing. (Incident 249844)
  838.  
  839.           +o The definition of a template class instantiation does
  840.             not include the member functions. (Incident 249849)
  841.  
  842.             Workaround: A member function definition for a template
  843.             class instantiation may be printed out using the
  844.             class-qualified name, prefixed by the template argument
  845.             list. For example, consider the following code segment:
  846.  
  847.             tttteeeemmmmppppllllaaaatttteeee<<<<ccccllllaaaassssssss TTTT>>>> ccccllllaaaassssssss vvvveeeeccccttttoooorrrr {{{{
  848.                 TTTT**** vvvv;;;;
  849.                 iiiinnnntttt sssszzzz;;;;
  850.             ppppuuuubbbblllliiiicccc::::
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.                                   - 14 -
  863.  
  864.  
  865.  
  866.                 vvvveeeeccccttttoooorrrr((((iiiinnnntttt))));;;;
  867.                 TTTT&&&& ooooppppeeeerrrraaaattttoooorrrr[[[[]]]]((((iiiinnnntttt))));;;;
  868.             }}}};;;;
  869.             vvvveeeeccccttttoooorrrr<<<<iiiinnnntttt>>>> vvvv1111((((22220000))));;;;
  870.  
  871.             In this example, the global names of the member
  872.             functions are <_i_n_t>_v_e_c_t_o_r::_v_e_c_t_o_r and
  873.             <_i_n_t>_v_e_c_t_o_r::_o_p_e_r_a_t_o_r[].
  874.  
  875.        5.1.2  _D_e_b_u_g_g_i_n_g__P_r_o_g_r_a_m__G_r_o_u_p_s__I_n_c_l_u_d_i_n_g__a__S_e_t_-_u_i_d__P_r_o_g_r_a_m
  876.        Because of standard IRIX security policies, the debugger can
  877.        not debug a program running as another user (unless you are
  878.        logged in as _r_o_o_t).  This restriction applies even to system
  879.        programs which are set-UID, and even when all you want to do
  880.        with the set-UID program is debug something that it in turn
  881.        runs.  It is common to use the system-provided set-UID
  882.        program _x_w_s_h (or _w_i_n_t_e_r_m, which in turn runs _x_w_s_h) in this
  883.        way.
  884.  
  885.        There are two basic ways to deal with this problem.  You can
  886.        become _r_o_o_t before starting your debugging session, which
  887.        grants you all necessary access rights (but may be
  888.        infeasible for your application or situation).  Or, you can
  889.        arrange to use a non-set-UID copy of the intermediary
  890.        program, for example with _c_h_m_o_d, or by making a copy of the
  891.        program with _c_p.
  892.  
  893.        There is also a bug in the IRIX 6.0 version of _x_w_s_h which
  894.        makes it unreliable if run non-set-UID.  You may be able to
  895.        use _x_t_e_r_m instead of _x_w_s_h for these applications, for
  896.        example by using _w_i_n_t_e_r_m and setting the environment
  897.        variable WWWWIIIINNNNTTTTEEEERRRRMMMM to xxxxtttteeeerrrrmmmm before starting your debugging
  898.        session (and providing a non-set-UID copy of _x_t_e_r_m).
  899.  
  900.        If your application depends on features of _x_w_s_h, can not use
  901.        _x_t_e_r_m instead, and can not be run as _r_o_o_t, then this
  902.        procedure will generally ensure that you can debug as non-
  903.        root:
  904.  
  905.           +o Make a non-set-uid copy of _x_w_s_h (ccccpppp ////uuuussssrrrr////ssssbbbbiiiinnnn////xxxxwwwwsssshhhh ....).
  906.  
  907.           +o Start several _x_w_s_h or _x_t_e_r_m windows, as the user who
  908.             will be doing the debugging.  Exit them all.  It is
  909.             important that they all be started together, all be
  910.             running at once, and then be exited immediately before
  911.             the debugging session begins.
  912.  
  913.           +o Debug your application.
  914.  
  915.           +o Set one or more breakpoints by function name ("stop in
  916.             main"), in the syscall panel, or with the ``Traps: Stop
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.                                   - 15 -
  929.  
  930.  
  931.  
  932.             at Function Entry'' menu - not by clicking in the glyph
  933.             bar of the main window.  (Traps set on a particular
  934.             source line, as by clicking, are not copied from one
  935.             program to the next.)
  936.  
  937.           +o Bring up the MPView, from the Admin menu.
  938.  
  939.           +o Be sure all the "copy traps...." boxes are checked in
  940.             its configuration dialog.
  941.  
  942.           +o Run your application, using MPView's ``Continue''
  943.             button as necessary and watching MPView for the
  944.             appearance of your subprocess.  Double-click it to
  945.             launch a debugger on it.
  946.  
  947.  
  948.        5.2  _W_o_r_k_S_h_o_p__F_i_x_+_C_o_n_t_i_n_u_e
  949.  
  950.        5.2.1  _L_i_m_i_t_a_t_i_o_n_s__o_f__F_i_x_+_C_o_n_t_i_n_u_e
  951.  
  952.           +o You cannot add or delete global variables or functions.
  953.  
  954.           +o You are restricted to editing the bodies of existing
  955.             non-inline functions. If you attempt to edit an inline
  956.             function, no warnings are emitted, but the results are
  957.             unpredictable.
  958.  
  959.             Incident 240481
  960.  
  961.           +o You cannot modify a function while the program is
  962.             sleeping in a system call, or is stopped on entry to a
  963.             system call.  The debugger will detect this condition
  964.             and prevent you from loading the modified function
  965.             until you return from the system call.
  966.  
  967.             You can set a trap on exit from the system call using
  968.             the System Call panel of cvd and continue the program
  969.             in order to get to a point where function loading is
  970.             allowed.
  971.  
  972.             Incident 244664
  973.  
  974.           +o The Multiprocess View capability of the debugger does
  975.             not interact well with the Fix and Continue feature.
  976.             sproc'ed and forked processes inherit the new
  977.             redefinition of the function.  However, when starting a
  978.             debugger session on the new process, the debugger is
  979.             not aware that the process contains function
  980.             redefinitions.  This means that there is no way to
  981.             deactivate the new definition in the new process after
  982.             a sproc() or a fork(). If the new function definition
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.                                   - 16 -
  995.  
  996.  
  997.  
  998.             is not desired in the new process, it is necessary to
  999.             stop the process on entry to fork() or sproc(),
  1000.             deactivate the modified function and activate it again
  1001.             on exit from fork() or sproc().
  1002.  
  1003.           +o Performance Analysis and Fix and Continue are mutually
  1004.             exclusive operations.  You should not run a performance
  1005.             experiment after you have modified a function.  In most
  1006.             cases, the debugger will detect attempts to mix
  1007.             Performance Analysis and Fix and Continue operations,
  1008.             and prevent them.
  1009.  
  1010.             Incident 245326
  1011.  
  1012.           +o The Fix and Continue feature is not supported for code
  1013.             compiled with the Delta/C++ (DCC) compiler. The current
  1014.             implementation does not detect this problem.
  1015.  
  1016.           +o Fix and Continue can only be used on ELF executables
  1017.             compiled in shared mode.  Fix and Continue is
  1018.             implemented by using the dynamic loader, which is not
  1019.             available in COFF or non-shared ELF executables.
  1020.  
  1021.             Incident 243574
  1022.  
  1023.           +o Fix and Continue is only supported on IRIX 5.3. In
  1024.             particular, Fix and Continue is not supported on IRIX
  1025.             5.2 and IRIX 6.x.
  1026.  
  1027.        5.2.2  _K_n_o_w_n__P_r_o_b_l_e_m_s__w_i_t_h__F_i_x__a_n_d__C_o_n_t_i_n_u_e
  1028.  
  1029.           +o The Disassembly View has not been updated to work with
  1030.             the Fix and Continue feature. As a result, you will
  1031.             notice the following behavior when viewing a modified
  1032.             function in Disassembly View:
  1033.  
  1034.                +o The filename displayed is incorrect, and reflects
  1035.                  the name of the temporary file used by the Fix and
  1036.                  Continue mechanism.
  1037.  
  1038.                +o The assembly instructions are not interleaved with
  1039.                  the source code.
  1040.  
  1041.                +o The line numbers shown in Disassembly View do not
  1042.                  reflect the line numbers used in the rest of the
  1043.                  debugger (i.e., instead of "7.3", the Disassembly
  1044.                  View will say line "9").
  1045.  
  1046.             Incident 243635
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.                                   - 17 -
  1061.  
  1062.  
  1063.  
  1064.           +o The initialization value of local statics in C may not
  1065.             be modified.  If you make such a change, it will
  1066.             silently be ignored. Since you are permitted to add new
  1067.             local statics, you can accomplish a change of the
  1068.             initialization value using the following workaround:
  1069.  
  1070.             /* Original function */
  1071.             void f() {
  1072.                static int i = 0; /* oops. This should be -1 */
  1073.             }
  1074.  
  1075.             /* New function */
  1076.             void f() {
  1077.                static int i = 0; /* oops. This should be -1 */
  1078.                static int first_time = 1;
  1079.                if (first_time) {
  1080.                   i = -1;
  1081.                   first_time = 0;
  1082.                }
  1083.             }
  1084.  
  1085.             Incident 246306
  1086.  
  1087.           +o In C it is legal to call a function without declaring
  1088.             it, and later declare the function to be static. For
  1089.             example:
  1090.  
  1091.                main(){
  1092.                   f();
  1093.                   return 0;
  1094.                }
  1095.  
  1096.                static int f(){
  1097.                }
  1098.  
  1099.             Since the Fix and Continue feature will only compile
  1100.             "main", and since there is no declaration for "f", the
  1101.             compiler will assume that "f" is an external function,
  1102.             and there will subsequently by a "Load Error" in the
  1103.             Interpreter Message window since the runtime loader
  1104.             will be unable to find an external definition for "f".
  1105.             The workaround is to make sure the compiler knows that
  1106.             "f" is static when you use modify "main" during a Fix
  1107.             and Continue operation:
  1108.  
  1109.                main(){
  1110.                   static int f();
  1111.                   f();
  1112.                   return 0;
  1113.                }
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.                                   - 18 -
  1127.  
  1128.  
  1129.  
  1130.             Incident 246317
  1131.  
  1132.           +o When executing an older version of a function, you will
  1133.             see the most recent source in the source window.
  1134.             Consequently the line numbers, PC highlight, and
  1135.             breakpoints displayed may be on the wrong lines.
  1136.  
  1137.           +o If you open a source file using "Source:Open...", the
  1138.             source file is opened in "Editable" mode by default.
  1139.             This prevents Fix and Continue operations on the file,
  1140.             and you will see the "Fix+Continue" button grayed out.
  1141.             If you wish to use Fix and Continue on this file, use
  1142.             the "Source:Make Read Only" menu option. If you use
  1143.             "Source:Open..." to open a source file in which you
  1144.             have previously modified functions, the modified
  1145.             functions will not be highlighted while the source file
  1146.             is editable.
  1147.  
  1148.             If you save a file in which some changes were made
  1149.             using Fix and Continue, and some changes were made
  1150.             using "Source:Open...", confusion may occur.  You can
  1151.             workaround this by using "Source:Make Editable"
  1152.             followed by "Source:Make Read Only". Another workaround
  1153.             is to switch to some other file and then switch back to
  1154.             the current file. Switching back can be accomplished by
  1155.             making the process stop in the file or by using
  1156.             "Source:Open..." followed by "Source:Make Read Only".
  1157.  
  1158.             Incidents 243627, 243629, 248842
  1159.  
  1160.           +o If you are stopped in a program, and you modify a
  1161.             function which is not the one you are stopped in, after
  1162.             the "Parse And Load" completes your source is
  1163.             repositioned at the line on which you are stopped,
  1164.             rather than at the function you just modified.
  1165.  
  1166.             Incident 246739
  1167.  
  1168.           +o When a "Parse and Load" is performed, a compiler is
  1169.             invoked to compile the modified function. Before
  1170.             performing the compile, the compilation process will do
  1171.             a "cd" so that the compilation takes place in the same
  1172.             directory as the original file was compiled in. This
  1173.             "cd" operation does not currently take path remapping
  1174.             into account, so you will have problems when you
  1175.             attempt to use "Fix and Continue" on an executable
  1176.             which was built on a different machine. The workaround
  1177.             is to make sure that you use "Fix and Continue" on an
  1178.             executable in the same environment as the one it was
  1179.             built in.  Another alternative is to adjust the command
  1180.             line options on the compile command (using the Build
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.                                   - 19 -
  1193.  
  1194.  
  1195.  
  1196.             Environment window) so that they will work in the
  1197.             debugging environment.
  1198.  
  1199.             Incident 246189
  1200.  
  1201.           +o The Fix and Continue mechanism does not currently check
  1202.             to make sure that a file has not been modified after it
  1203.             was last compiled. If you modify a function using Fix
  1204.             and Continue, save the source back to its original
  1205.             file, and forget to rebuild your application after
  1206.             exiting the debugger, you will see unpredictable result
  1207.             if you re-enter the debugger and attempt to use Fix and
  1208.             Continue. For example, the debugger may think that
  1209.             function "f" is on lines 15 to 20, whereas your
  1210.             previous changes may have repositioned the function on
  1211.             lines 17 to 22. When you select "Fix+Continue:Edit" if
  1212.             you notice that the edit region does not cover the
  1213.             entire body of the function, you should exit the
  1214.             debugger and rebuild your application.
  1215.  
  1216.             Incident 245098
  1217.  
  1218.           +o If your original build compiled multiple files with a
  1219.             single command line, this same command line will be run
  1220.             when using Fix and Continue to modify a function in any
  1221.             of those files, causing unnecessary recompilations of
  1222.             the other files, and possibly erroneous results.  For
  1223.             best results, compile files one at a time using the -c
  1224.             option of the compiler.  If this is not possible, use
  1225.             the Build Environment view to modify the command line
  1226.             and remove all file names from it (Fix and Continue
  1227.             will add in the file actually being compiled
  1228.             automatically).
  1229.  
  1230.           +o When you use the "Fix and Continue->Edit" menu item,
  1231.             the region you are allowed to edit begins with the line
  1232.             containing the first "{" of your function.  This line
  1233.             would include the line containing the function and
  1234.             parameter declaration, for the coding style shown
  1235.             below:
  1236.  
  1237.                void f(int y){
  1238.                   /* .... */
  1239.                }
  1240.  
  1241.             In such cases, you should make sure you do not change
  1242.             the function name and parameter profile. The
  1243.             implementation does not currently check that you do not
  1244.             make such changes, but you may receive a message like
  1245.             this:
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.                                   - 20 -
  1259.  
  1260.  
  1261.  
  1262.                No reply from PCS;
  1263.                unknown error while loading dso for the modified function
  1264.  
  1265.             Incident 245299
  1266.  
  1267.           +o If a "stop exit" trap is placed in a function, and Fix
  1268.             and Continue is used on the function after hitting the
  1269.             exit trap, then if execution can continue in the new
  1270.             function, the PC is moved back to the beginning of the
  1271.             line (it is in the epilogue, at the "jr ra"
  1272.             instruction). This means the epilogue is re-executed.
  1273.             This could cause problems if the stack pointer has
  1274.             already been decremented, because now it will get
  1275.             decremented twice. Your program may occasionally work
  1276.             if the stack decrement happens to be after the "jr ra"
  1277.             instruction. The implementation currently does not
  1278.             always detect this condition.
  1279.  
  1280.             The workaround is to reposition the PC at the "jr ra"
  1281.             using PC->JumpTo after your F&C has completed.
  1282.  
  1283.             F&C and templates
  1284.  
  1285.           +o Using F&C on functions which use templates are not
  1286.             completely supported in this release. Typically, if the
  1287.             change involves instantiating new functions, then such
  1288.             a  change is not supported in this release. If the
  1289.             process is stopped when this change is made, the F&C
  1290.             error message window will display the error message
  1291.             from rld under the PCS error messages. Otherwise, views
  1292.             would temporarily show that the change is ok, but when
  1293.             the process is run later , load error message will be
  1294.             reported and the change is switched back to edited
  1295.             state.
  1296.  
  1297.             The error message would be something like:  :
  1298.             26095:/tmp_mnt/hosts/xanadu/usr/people/pal/kim/mnm:
  1299.             rld: Fatal Error: unresolvable symbol in
  1300.             /var/tmp/cvintp26042/cvfn1.3.so:
  1301.                     static_allocator__15vector__pt__2_i
  1302.  
  1303.             Incident 249309
  1304.  
  1305.  
  1306.        5.3  _W_o_r_k_S_h_o_p__M_o_t_i_f__A_n_a_l_y_z_e_r
  1307.  
  1308.           +o The Motif Analyzer requires IRIX 5.3 or later for
  1309.             correct operation.  The instrumented libraries have
  1310.             been tested on older versions of IRIX and may result in
  1311.             compatibility problems with other shared libraries.
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.                                   - 21 -
  1325.  
  1326.  
  1327.  
  1328.           +o The Motif Analyzer may produce unexpected results when
  1329.             used with an application compiled on a pre-IRIX 5.3
  1330.             system using static libraries, and with non-Motif (e.g.
  1331.             Xaw) applications.  In particular, the widget selection
  1332.             and widget tree functionality may not work.
  1333.  
  1334.           +o The instrumented, debug Motif library shipped with the
  1335.             MegaDev.sw.motif subsystem and installed in
  1336.             /usr/lib/WorkShop/Motif contain the IRIX 5.3 version of
  1337.             motif_eoe.sw.eoe up to and including patch 258.  If you
  1338.             are debugging a Motif-related problem in your
  1339.             application and the problem is not reproducible using
  1340.             the instrumented Motif library in
  1341.             /usr/lib/WorkShop/Motif, it may be fixed with the patch
  1342.             258 version of motif_eoe.sw.eoe.
  1343.  
  1344.           +o If you create traps in the Motif Analyzer window using
  1345.             the Breakpoints examiner, trap items will appear in the
  1346.             Trap Manager window of the WorkShop Debugger.  These
  1347.             items will be labeled "MotifBreak."  You should not
  1348.             attempt to modify or delete these traps using the Trap
  1349.             Manager.  Instead, always use the Breakpoints examiner
  1350.             to modify or delete your Motif-related breakpoints.
  1351.  
  1352.           +o If you install the MegaDev.sw.motif subsystem and then
  1353.             reinstall the WorkShop.sw.cvd subsystem, the "Motif
  1354.             Analyzer" item will disappear from the Views menu in
  1355.             the WorkShop Debugger.  Reinstalling the
  1356.             MegaDev.sw.motif subsystem will correct the problem.
  1357.  
  1358.           +o If you install the WorkShop.sw.cvd and MegaDev.sw.motif
  1359.             subsystems, and then remove only the MegaDev.sw.motif
  1360.             subsystem, the "Motif Analyzer" menu item will still
  1361.             exist in the Views menu in the WorkShop Debugger.
  1362.             Selecting this menu item, however, will result in an
  1363.             error dialog.  Reinstalling the WorkShop.sw.cvd
  1364.             subsystem will remove the item from the Views menu.
  1365.  
  1366.           +o Occasionally, the Motif Analyzer display will remain
  1367.             inactive after switching between processes using
  1368.             WorkShop's "Switch Process" or "Switch Executable" menu
  1369.             items, or when rerunning the process after changing the
  1370.             command arguments.  If this happens, close the Motif
  1371.             Analyzer window and use WorkShop's Views menu to bring
  1372.             it up again.
  1373.  
  1374.           +o If your application connects to a remote X display and
  1375.             you do not set LD_LIBRARY_PATH to include
  1376.             /usr/lib/WorkShop/Motif, any Editres-type operations
  1377.             (e.g. widget select and widget tree) will operate on
  1378.             the local display and not work correctly.  Either run
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.                                   - 22 -
  1391.  
  1392.  
  1393.  
  1394.             your program using the local X display or change
  1395.             LD_LIBRARY_PATH as advised.
  1396.  
  1397.           +o A small number of applications build their widget
  1398.             hierarchy in such a way that Editres widget selection
  1399.             operations cause them to exit with an X error.  If your
  1400.             application falls into this category, then using the
  1401.             Motif Analyzer widget select functionality will cause
  1402.             the same thing to happen.
  1403.  
  1404.  
  1405.        5.4  _W_o_r_k_S_h_o_p__B_u_i_l_d__A_n_a_l_y_z_e_r
  1406.  
  1407.        If target or dependency names are specified using
  1408.        parentheses to denote files stored within an archive
  1409.        library, _c_v_b_u_i_l_d will use a single node to represent the
  1410.        archive library, rather than individual nodes for each file
  1411.        within it.
  1412.  
  1413.  
  1414.        5.5  _W_o_r_k_S_h_o_p__S_t_a_t_i_c__A_n_a_l_y_z_e_r
  1415.  
  1416.        5.5.1  _G_e_n_e_r_a_l__K_n_o_w_n__P_r_o_b_l_e_m_s
  1417.  
  1418.           +o The Directory Query "List Files" works only when the
  1419.             query target is a full path name of a directory.  For
  1420.             example, it works on the target "/usr/include", but not
  1421.             on a target like "include".
  1422.  
  1423.             Workaround: Select the General Option "Full Pathnames".
  1424.             Then any directory names displayed will contain full
  1425.             paths, and so the "List Files" query will cork on them
  1426.             correctly.
  1427.  
  1428.           +o If you use _c_v_s_t_a_t_i_c to analyze a fileset and then
  1429.             change one or more of the header files included by the
  1430.             files in the fileset, rescanning the fileset will not
  1431.             detect the change.  Rescanning only detects changes to
  1432.             source files listed in the fileset.  Similarly, if you
  1433.             remove a source file from a fileset and rescan, the
  1434.             header files included by that file are not removed from
  1435.             the database. (Incident #179731)
  1436.  
  1437.             Workaround: If you have changed one or more files in a
  1438.             fileset (or included by files in a fileset), you can
  1439.             get a consistent database by selecting ``Force Scan''
  1440.             from the Admin menu.
  1441.  
  1442.           +o Some printers may clip the output when printing a
  1443.             PostScript version of graph saved by _c_v_s_t_a_t_i_c.
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.                                   - 23 -
  1457.  
  1458.  
  1459.  
  1460.             Workaround: None, except trying another printer, or
  1461.             re-laying out the graph by hand to avoid clipping.
  1462.  
  1463.        5.5.2  _K_n_o_w_n__P_r_o_b_l_e_m_s__w_i_t_h__M_i_x_e_d__L_a_n_g_u_a_g_e_s
  1464.  
  1465.           +o If you analyze a program that contains both Fortran and
  1466.             C routines, _c_v_s_t_a_t_i_c in scanner mode does not recognize
  1467.             that the C function ffffoooooooo____ and the Fortran function ffffoooooooo
  1468.             refer to the same routine.  In parser mode, _c_v_s_t_a_t_i_c
  1469.             will identify the routines correctly, if it analyzes
  1470.             the C file containing ffffoooooooo____ before the Fortran file that
  1471.             calls ffffoooooooo.  So, make sure that your C files appear
  1472.             earlier in the fileset than your Fortran files.
  1473.  
  1474.  
  1475.  
  1476.  
  1477.  
  1478.  
  1479.  
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.                                   - 24 -
  1523.  
  1524.  
  1525.  
  1526.  
  1527.        5.5.3  _G_e_n_e_r_a_l__K_n_o_w_n__P_r_o_b_l_e_m_s__i_n__S_c_a_n_n_e_r__M_o_d_e
  1528.  
  1529.           +o In general, _c_v_s_t_a_t_i_c does not require code to be able
  1530.             to be compiled.  _c_v_s_t_a_t_i_c should provide useful
  1531.             information even when code has syntax errors. However,
  1532.             there are several requirements that must be met for
  1533.             _c_v_s_t_a_t_i_c to work properly. In C and C++, _c_v_s_t_a_t_i_c
  1534.             relies on the existence of matching braces to determine
  1535.             the beginning and ending of blocks and bodies of
  1536.             functions. In Fortran, _c_v_s_t_a_t_i_c relies on the existence
  1537.             of matching end statements. Functions without closing
  1538.             braces, or end statements, or code with too many end
  1539.             statements or mismatched braces can cause unpredictable
  1540.             results. In C, it may be necessary to use _c_v_s_t_a_t_i_c's
  1541.             ----pppprrrreeeepppprrrroooocccceeeessssssss option with heavily _i_f_d_e_f'd code to achieve
  1542.             matched braces.
  1543.  
  1544.             If any of these limitations of scanner mode keeps
  1545.             _c_v_s_t_a_t_i_c from being useful, using parser mode may be
  1546.             the right solution.
  1547.  
  1548.           +o _c_v_s_t_a_t_i_c accepts regular expressions in nearly all
  1549.             fields. This can occasionally cause problems if you
  1550.             unintentionally use a pattern without realizing it is a
  1551.             regular expression. For example, specifying a filename
  1552.             of ffffoooooooo....cccc++++++++ usually fails, because ++++ is a special
  1553.             character in regular expressions.
  1554.  
  1555.             Workaround: Backslash all regular expression special
  1556.             characters when not used to specify a wildcard pattern.
  1557.             For example, the filename mentioned above would be
  1558.             entered as ffffoooooooo....cccc\\\\++++\\\\++++.
  1559.  
  1560.           +o The _c_v_s_t_a_t_i_c Variable query, ``Who Sets'' recognizes
  1561.             only variable assignments that use ``='' to assign
  1562.             directly to a variable.  This query does not recognize
  1563.             or account for aggregate initialization statements in C
  1564.             or C++, references in C++, assignments made as a result
  1565.             of passing or operating on pointers in C, or data,
  1566.             equivalence, common, or assign statements in Fortran.
  1567.  
  1568.             Workaround. Use ``Who References'' to see all locations
  1569.             in which the variable is used and to visually inspect
  1570.             for assignments.
  1571.  
  1572.           +o By default, _c_v_s_t_a_t_i_c does not honor _i_f_d_e_f's in source
  1573.             code. Much of the time, this is desirable behavior.
  1574.             _c_v_s_t_a_t_i_c allows you to find _a_l_l references that satisfy
  1575.             a query. However, this may result in an incorrect or
  1576.             misleading function call tree. Heavily _i_f_d_e_f'd code may
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.                                   - 25 -
  1589.  
  1590.  
  1591.  
  1592.             also confuse _c_v_s_t_a_t_i_c, because (in C) _c_v_s_t_a_t_i_c relies
  1593.             on matching braces to detect the end of functions.
  1594.  
  1595.             Workaround: Use the ----pppprrrreeeepppprrrroooocccceeeessssssss flag when starting
  1596.             _c_v_s_t_a_t_i_c. This makes _c_v_s_t_a_t_i_c run much more slowly, but
  1597.             it honors most _i_f_d_e_fs.
  1598.  
  1599.           +o _c_v_s_t_a_t_i_c recognizes many common C, C++, and Fortran
  1600.             language patterns.  However, all three languages allow
  1601.             programmers to write code that is not easily identified
  1602.             by patterns.
  1603.  
  1604.             Workaround: If you find that _c_v_s_t_a_t_i_c misses or
  1605.             misidentifies parts of a program, you can usually
  1606.             resort to string, regular expression, or symbol queries
  1607.             to find the information you are looking for.
  1608.  
  1609.           +o Files containing very long lines are not handled in
  1610.             scanner mode. If a file contains any line longer than
  1611.             3000 characters, _c_v_s_t_a_t_i_c's scanner will fail.
  1612.  
  1613.             Workaround: Use parser mode, or shorten your source
  1614.             lines.
  1615.  
  1616.        5.5.4  _K_n_o_w_n _P_r_o_b_l_e_m_s _U_s_i_n_g _c_v_s_t_a_t_i_c _i_n _S_c_a_n_n_e_r _M_o_d_e _w_i_t_h
  1617.        _C++  _c_v_s_t_a_t_i_c analyzes C++ source code much more accurately
  1618.        in parser mode than in scanner mode.  The following problems
  1619.        are known to occur in scanner mode.  They can be avoided by
  1620.        following the workaround suggestions, or by using parser
  1621.        mode.
  1622.  
  1623.           +o _c_v_s_t_a_t_i_c does not do macro expansion, so classes based
  1624.             on macros used to simulate C++ parameterized types are
  1625.             not detected.
  1626.  
  1627.           +o _c_v_s_t_a_t_i_c does not completely handle function calls made
  1628.             through function pointers, in C or C++. In C++, this
  1629.             includes calls to member functions made through object
  1630.             pointers.  For example, consider the following code
  1631.             segment:
  1632.  
  1633.             ssssaaaammmmpppplllleeeeffffuuuunnnnccccttttiiiioooonnnn (((())))
  1634.             {{{{
  1635.                AAAA ****oooobbbbjjjjeeeecccctttt1111 ==== nnnneeeewwww AAAA(((())));;;;
  1636.                BBBB ****oooobbbbjjjjeeeecccctttt2222 ==== nnnneeeewwww BBBB(((())));;;;
  1637.                oooobbbbjjjjeeeecccctttt1111---->>>>ffffuuuunnnncccc(((())));;;;
  1638.                oooobbbbjjjjeeeecccctttt2222---->>>>ffffuuuunnnncccc(((())));;;;
  1639.             }}}}
  1640.  
  1641.             In this example, _c_v_s_t_a_t_i_c correctly reports that
  1642.             samplefunction() calls func() two times. However, it
  1643.  
  1644.  
  1645.  
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.                                   - 26 -
  1655.  
  1656.  
  1657.  
  1658.             cannot determine that these two function calls are
  1659.             actually made to two different member functions,
  1660.             implemented by two different classes. Similarly,
  1661.             _c_v_s_t_a_t_i_c does not know about the _t_h_i_s pointer.
  1662.  
  1663.             Workaround: Don't try to display full function call
  1664.             trees for C++. Instead use queries like ``Who Calls
  1665.             <function>''or ``Who Is Called By <function>'' which
  1666.             produce meaningful results.
  1667.  
  1668.           +o _c_v_s_t_a_t_i_c does not understand overloaded functions.
  1669.  
  1670.             Workaround: Use the text view for all queries involving
  1671.             overloaded functions.
  1672.  
  1673.           +o C++ allows extensive use of operator overloading, which
  1674.             allows you to write code that can obscure what is
  1675.             really happening in the code. Because _c_v_s_t_a_t_i_c is
  1676.             designed around a pattern matcher, novel constructs
  1677.             produced by overloading operators are not normally
  1678.             detected. Constructs that conform to normal language
  1679.             conventions should normally be found. For example, if A
  1680.             and B are objects, and the ``='' operator has been
  1681.             overloaded to indicate an assignment of the contents of
  1682.             object B to the contents of object A, _c_v_s_t_a_t_i_c should
  1683.             be able to handle this situation. However, if some
  1684.             unusual overloading conventions have been used (say,
  1685.             using ``[]'' to mean a function call), _c_v_s_t_a_t_i_c does
  1686.             not show the same results as the C compiler.
  1687.  
  1688.             Workaround: If you have such code, use string or
  1689.             regular expression searches, or symbol searches to find
  1690.             what you are looking for.
  1691.  
  1692.           +o C++ programs containing templates are not well
  1693.             understood by scanner mode.
  1694.  
  1695.             Workaround: Use parser mode.
  1696.  
  1697.        5.5.5  _K_n_o_w_n__p_r_o_b_l_e_m_s__U_s_i_n_g__c_v_s_t_a_t_i_c__w_i_t_h__F_o_r_t_r_a_n
  1698.  
  1699.           +o Problem: cvstatic changes case in source files.
  1700.  
  1701.             Workaround:  For best results, ignore case:
  1702.  
  1703.             Because the Fortran compilers translate Fortran
  1704.             programs to lower (for Fortran 77) or upper (for
  1705.             Fortran 90) case when analyzing them, you may have
  1706.             trouble selecting a symbol name from the Source View
  1707.             and then using the selection as the target of a query.
  1708.             Therefore, when using the Static Analyzer on Fortran
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.                                   - 27 -
  1721.  
  1722.  
  1723.  
  1724.             sources, it is best to select the Ignore Case option,
  1725.             either through the General Option menu, or persistently
  1726.             through the use of the X resource mechanism thus:
  1727.  
  1728.                     cvstatic*ignoreCase: True
  1729.  
  1730.           +o Problem: Fortran file suffixes are ambiguous.
  1731.  
  1732.             Workaround: Tell cvstatic what suffixes you use for
  1733.             which Fortran variant.
  1734.  
  1735.             Both Fortran 77 and Fortran 90 accept files with the
  1736.             the suffixes .f and .F.  So, there is no obvious way
  1737.             for the Static Analyzer to tell whether a source file
  1738.             is Fortran 77 or Fortran 90.
  1739.  
  1740.             To indicate that you want a particular suffix to
  1741.             correspond to a particular language, you can set the
  1742.             suffixSource X resource before running cvstatic.  For
  1743.             example:
  1744.  
  1745.             *suffixSource: C++.c++ C++.C C++.cxx C++.h C.c
  1746.             Fortran.f Fortran90.F Fortran90.f90
  1747.  
  1748.             This line in your .Xdefaults file indicates that you
  1749.             want files ending .f to be analyzed as Fortran 77
  1750.             codes, while files ending .F or .f90 are Fortran 90.
  1751.  
  1752.             You may want to analyze a set of files in which some
  1753.             files ending .f are Fortran 77 while other files with
  1754.             the same suffix are Fortran 90.  If so, the only way to
  1755.             distinguish them is for you manually to edit the
  1756.             cvstatic.fileset file and make sure that each filename
  1757.             is followed by the correct driver.  For example, these
  1758.             two lines in the fileset file indicate that foo.f is a
  1759.             Fortran 77 file, while bar.f is Fortran 90:
  1760.  
  1761.                 ////uuuussssrrrr////ppppeeeeoooopppplllleeee////yyyyoooouuuu////ffffoooooooo....ffff ffff77777777
  1762.                 ////uuuussssrrrr////ppppeeeeoooopppplllleeee////yyyyoooouuuu////bbbbaaaarrrr....ffff ffff99990000
  1763.  
  1764.        _c_v_s_t_a_t_i_c analyzes Fortran source code much more accurately
  1765.        in parser mode than in scanner mode.  The following problems
  1766.        are known to occur in scanner mode.  They can be avoided by
  1767.        following the workaround suggestions, or by using parser
  1768.        mode.
  1769.  
  1770.           +o _c_v_s_t_a_t_i_c occasionally misses function calls and other
  1771.             statements that directly follow an _i_f statement on the
  1772.             same line.
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.                                   - 28 -
  1787.  
  1788.  
  1789.  
  1790.           +o _c_v_s_t_a_t_i_c uses a pattern matching approach. This
  1791.             approach does not allow the tool to detect the
  1792.             irregular use of spaces within Fortran symbols, even
  1793.             though these are allowed by the Fortran compiler. For
  1794.             example, the Fortran compiler accepts the statement:
  1795.  
  1796.                    ssssuuuubbbb rrrroooouuuuttttiiiinnnneeee mmmmyyyy
  1797.                   1111ffffuuuunnnncccc ttttiiiioooonnnn
  1798.  
  1799.             as if it were written:
  1800.  
  1801.                   ssssuuuubbbbrrrroooouuuuttttiiiinnnneeee mmmmyyyyffffuuuunnnnccccttttiiiioooonnnn
  1802.  
  1803.             _c_v_s_t_a_t_i_c does not handle such conventions.
  1804.  
  1805.             Workaround: None in scanner mode. Silicon Graphics
  1806.             strongly suggests changing such code to use a more
  1807.             readable coding style.
  1808.  
  1809.           +o _c_v_s_t_a_t_i_c does not support the use of Fortran keywords
  1810.             for uses other than their intrinsic function. For
  1811.             example, _c_v_s_t_a_t_i_c always recognizes word ``if'' as
  1812.             starting a conditional statement. Programs that use
  1813.             ``if'' as a variable or function name are not analyzed
  1814.             correctly.
  1815.  
  1816.             Workaround: None in scanner mode. Silicon Graphics
  1817.             strongly suggests changing such code to use a more
  1818.             readable coding style.
  1819.  
  1820.           +o In some situations, _c_v_s_t_a_t_i_c can mistake references to
  1821.             arrays as function calls. This is particularly true
  1822.             when the Fortran code relies on include files to
  1823.             declare arrays, common blocks, and so on. _c_v_s_t_a_t_i_c does
  1824.             not analyze header files at the point at which they
  1825.             occur, but simply adds them to the list of files to be
  1826.             analyzed. This contributes greatly to the speed of
  1827.             _c_v_s_t_a_t_i_c, but means that _c_v_s_t_a_t_i_c does not have various
  1828.             type declarations available to it. Because Fortran
  1829.             arrays cannot be differentiated from function calls
  1830.             without a declaration, _c_v_s_t_a_t_i_c identifies arrays not
  1831.             defined in the file in which they are referenced as
  1832.             function calls.
  1833.  
  1834.             Workaround: Use the Results Filter to exclude
  1835.             ``external'' functions. This limits all queries to
  1836.             those functions actually defined in the fileset.
  1837.             Excluding external functions hides all array references
  1838.             erroneously identified as function calls, but also
  1839.             hides all calls to library functions, intrinsic
  1840.             functions, or other routines declared outside the
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.                                   - 29 -
  1853.  
  1854.  
  1855.  
  1856.             fileset.
  1857.  
  1858.        5.5.6  _K_n_o_w_n__P_r_o_b_l_e_m_s__U_s_i_n_g__c_v_s_t_a_t_i_c__i_n__P_a_r_s_e_r__M_o_d_e
  1859.             Sometimes the General query "Where Symbol Used" fails
  1860.             to report some call sites, if the target of the query
  1861.             was a function.
  1862.  
  1863.             WorkAround: Use the Function query "Who Calls" or
  1864.             "Where Function Used" to get a complete list of places
  1865.             wehre the target function is called or otherwise used.
  1866.  
  1867.           +o The query Where Type Used may return duplicate results
  1868.             in C and C++ programs.  For example, asking Where Type
  1869.             Used Foo will produce two copies of the result showing
  1870.             the definition of the symbol
  1871.  
  1872.                        FFFFoooooooo ffff;;;;
  1873.  
  1874.             If one of these locations is shown without a function
  1875.             field and one is shown with a function, the latter is
  1876.             correct.
  1877.  
  1878.             Workaround: If you are explicitly looking for
  1879.             definitions, use the queries List Data of Type or List
  1880.             Functions of Type instead.  Otherwise, just ignore the
  1881.             duplications.
  1882.  
  1883.           +o The query Where Type Used is confusing about pointers
  1884.             in C and C++.
  1885.  
  1886.             If you ask Where Type Used about a user-defined type
  1887.             named Foo, the query will display all uses of Foo,
  1888.             including uses of types like Foo*, Foo**, Foo[], etc.
  1889.  
  1890.             But if you ask Where Type Used about a built-in type
  1891.             like void or char, the query will display only uses of
  1892.             that exact type.
  1893.  
  1894.             Workaround: Query explicitly about typenames like
  1895.             void*, char**, etc, that contain no user-defined
  1896.             typenames.
  1897.  
  1898.           +o Queries on "integer" and "real" in fortran don't work.
  1899.  
  1900.             Fortran reports integer types as having typenames I*4
  1901.             and I*8, real types with typenames R*4, R*8, complex
  1902.             types with typenames CM*8 and CM*16, and logical types
  1903.             as L*4.
  1904.  
  1905.             Workaround: To inquire about uses and declarations with
  1906.             these types, enter I*4 (or whatever) into the target
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.                                   - 30 -
  1919.  
  1920.  
  1921.  
  1922.             field instead of "integer".
  1923.  
  1924.           +o Mismatched member function declarations and definitions
  1925.             are not recognized by _c_v_s_t_a_t_i_c'_s parser.  The parser
  1926.             runs into trouble processing a member function if the
  1927.             signature of its declaration and definition are not
  1928.             identical.  For example, if the code contains something
  1929.             like this:
  1930.  
  1931.             ttttyyyyppppeeeeddddeeeeffff iiiinnnntttt**** iiiinnnnttttppppttttrrrr;;;;
  1932.  
  1933.             ccccllllaaaassssssss AAAA {{{{
  1934.             ppppuuuubbbblllliiiicccc::::
  1935.                 AAAA ((((iiiinnnntttt **** iiii))));;;;
  1936.             }}}};;;;
  1937.  
  1938.             AAAA::::::::AAAA ((((iiiinnnnttttppppttttrrrr iiii)))) {{{{
  1939.             }}}}
  1940.  
  1941.             the parser will print the error message "no record for
  1942.             method A::A?" and terminate processing of the file.
  1943.  
  1944.             Workaround: analyze code like this in scanner mode, or
  1945.             change the type signatures so that the definition and
  1946.             declaration match.
  1947.  
  1948.           +o _c_v_s_t_a_t_i_c's parser mode is better at building a new
  1949.             database than at modifying an existing one.  If you
  1950.             build a parser-mode database and then change a file and
  1951.             reparse it, the database will grow each time you rescan
  1952.             the file.  Not all space is reclaimed.  Additional arcs
  1953.             may appear in the Call Tree view representing defunct
  1954.             call site information.
  1955.  
  1956.             Workaround: After a few files are modified and re-
  1957.             analyzed, it is best to use Force Scan to rebuild the
  1958.             entire parser-mode database. For a large code base that
  1959.             is slow to parse, you can use the -batch flag to
  1960.             rebuild the database overnight.
  1961.  
  1962.           +o Functions generated by templates are recognized and
  1963.             displayed by _c_v_s_t_a_t_i_c, but it treats them as external
  1964.             functions:  functions that are declared or used within
  1965.             the fileset but are not defined there. Consequently,
  1966.             they do not appear in the results of the ``Query List
  1967.             All Functions''.
  1968.  
  1969.             Workaround: Use specific queries about these functions,
  1970.             like ``Where Function Called'', or add them manually to
  1971.             Call Tree graphs.
  1972.  
  1973.  
  1974.  
  1975.  
  1976.  
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.                                   - 31 -
  1985.  
  1986.  
  1987.  
  1988.           +o The function "main" appears in the list of Functions
  1989.             Not Called, if it is not called explicitly from the
  1990.             source code.  ("main" is rarely called explicitly.)
  1991.  
  1992.             Workaround: You can add the function "main" manually to
  1993.             any graphical display of functions.
  1994.  
  1995.           +o Graphical display of a single member function called
  1996.             through derived classes is incomplete.  If a C++ member
  1997.             function FFFFoooooooo::::::::FFFFuuuunnnncccc is called through classes derived
  1998.             from the ccccllllaaaassssssss FFFFoooooooo, each derived function FFFFuuuunnnncccc will
  1999.             appear as a separate function in the Text View list of
  2000.             functions.  However, only one node will appear for FFFFuuuunnnncccc
  2001.             in the Call Tree View.
  2002.  
  2003.             Workaround: To see the full list of definitions and
  2004.             calls of FFFFuuuunnnncccc, use Text Mode.  If you double click on
  2005.             the definition of one of the derived FFFFuuuunnnnccccs, you will
  2006.             navigate either to the definition of the function (if
  2007.             you click on the version in FFFFoooooooo), or to the definition
  2008.             of the derived class through which FFFFuuuunnnncccc was called.
  2009.  
  2010.           +o If you are analyzing C++ code in which multiple non-
  2011.             member functions have the same name, _c_v_s_t_a_t_i_c will
  2012.             think they are all the same function with one
  2013.             definition and several declarations.
  2014.  
  2015.             Workaround: You can get to the definitions by using the
  2016.             ``Where Defined'' and ``Where Declared'' queries on
  2017.             functions.
  2018.  
  2019.           +o When you first bring up _c_v_s_t_a_t_i_c, if you switch the
  2020.             view from Text View to a graph view before building the
  2021.             parser database and doing your first query, the graph
  2022.             may incorrectly display as empty.
  2023.  
  2024.             Workaround:  Stay in Text View to perform your first
  2025.             query, and then switch to whichever graph view you
  2026.             wish.  Or, if you have already brought up _c_v_s_t_a_t_i_c in a
  2027.             graph view and built the database, hit ``Rescan'' in
  2028.             the Admin menu, and then redo your query.
  2029.  
  2030.  
  2031.        5.6  _W_o_r_k_S_h_o_p__C_+_+__B_r_o_w_s_e_r
  2032.  
  2033.           +o The _C++ _B_r_o_w_s_e_r currently works only on files in the
  2034.             parser fileset.  So if you have a fileset which has
  2035.             only files in the scanner fileset, the browser will not
  2036.             work. To generate the database, you have to put files
  2037.             in the parser fileset and issue a rebuild in _c_v_s_t_a_t_i_c.
  2038.             Once the database is created you can use Browser to
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.                                   - 32 -
  2051.  
  2052.  
  2053.  
  2054.             examine the C++ classes.
  2055.  
  2056.           +o When using the C++ Browser, if you make changes to the
  2057.             code in the files that are present in the fileset, the
  2058.             changes will not be reflected in the information
  2059.             presented by the C++ Browser until you issue a Rescan
  2060.             command in _c_v_s_t_a_t_i_c, as follows:
  2061.  
  2062.             *    Make your changes.
  2063.  
  2064.             *    Exit the C++ Browser (but not cvstatic).
  2065.  
  2066.             *    Issue a FFFFoooorrrrcccceeee SSSSccccaaaannnn from the cvstatic AAAAddddmmmmiiiinnnn menu.
  2067.  
  2068.             *    Restart the browser by selecting AAAAddddmmmmiiiinnnn/CCCC++++++++ BBBBrrrroooowwwwsssseeeerrrr
  2069.                  menu in cvstatic.
  2070.  
  2071.             Incident 186990.
  2072.  
  2073.           +o When using the C++ browser, if you create and close (or
  2074.             quit) the Class Graph or Call Graph windows many times,
  2075.             some times you may find that it will make the tool core
  2076.             dump or exit with X errors. This is due to some known
  2077.             defects in deletion of widgets in Xm and Sgm.
  2078.  
  2079.             Incident 204472.
  2080.  
  2081.           +o Duplicate class definitions encountered in your files
  2082.             in the parser fileset will end up as a single class
  2083.             with accumulating members from both the definitions.
  2084.             This happens when the file defining the class is
  2085.             included from two different paths or there are two
  2086.             genuine class definitions for the same class name in
  2087.             your fileset.
  2088.  
  2089.             Incident 206922.
  2090.  
  2091.           +o If you use typedefs, and use it to give alternate names
  2092.             to classes (as in _t_y_p_e_d_e_f _c_l_a_s_s _A _B;) - you may that
  2093.             the Build Window shows some warnings about not finding
  2094.             the class B and that the information collected about
  2095.             the usage of class A will be missing many of the
  2096.             references through its typedef B.
  2097.  
  2098.             This kind of typedef is more commonly found in template
  2099.             code. There is no good workaround currently, other than
  2100.             not using the typedef in question.
  2101.  
  2102.             Incident 217830.
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.  
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.                                   - 33 -
  2117.  
  2118.  
  2119.  
  2120.           +o If you use typedefs, and use it inconsistently in
  2121.             declaring and defining class members (as in the
  2122.             following example), you will find that information
  2123.             regarding those members is either missing or faulty.
  2124.             The workaround is to use the same prototype at the
  2125.             point of definition as at the point of declaration.
  2126.  
  2127.                 ttttyyyyppppeeeeddddeeeeffff iiiinnnntttt IIIINNNNTTTT;;;;
  2128.                 ccccllllaaaassssssss AAAA {{{{
  2129.                    vvvvooooiiiidddd ffffoooooooo ((((IIIINNNNTTTT))));;;;
  2130.                 }}}};;;;
  2131.  
  2132.                 vvvvooooiiiidddd AAAA::::::::ffffoooooooo ((((iiiinnnntttt vvvvaaaallll)))) ............   //////// ggggeeeettttssss wwwwaaaarrrrnnnniiiinnnngggg,,,, aaaannnndddd iiiissss mmmmiiiissssssssiiiinnnngggg
  2133.                                             //////// ffffrrrroooommmm ssssttttaaaattttiiiicccc aaaannnnaaaallllyyyyssssiiiissss iiiinnnnffffoooo....
  2134.  
  2135.             Incident 184455.
  2136.  
  2137.           +o Usage information for template classes is managed only
  2138.             on a per-instantiation basis.  If you use templates in
  2139.             your code, then each instantiation, and the template
  2140.             itself, will show up as classes in the C++ Browser.
  2141.  
  2142.             For instance, if you have a template class Foo<T>, then
  2143.             there will be a class called FOO<T> and classes FOO<A>,
  2144.             FOO<B> etc., for the template definition prototype of
  2145.             FOO and its instantiations with A, B, etc.,
  2146.             respectively. And the usage information on FOO<T>
  2147.             currently shown is not the amalgamation of usage
  2148.             information on its instantiations FOO<A>, FOO<B>, etc.
  2149.  
  2150.           +o Be careful about overwriting man pages which are
  2151.             generated using the automatic class man page generation
  2152.             facility.
  2153.  
  2154.             When you generate a manpage for a class, through the
  2155.             C++ browser, you get a skeleton, in which you have to
  2156.             fill in all the descriptions. Please remember that if
  2157.             you change the class and generate a new man page for
  2158.             that class again, your changes to the file will be lost
  2159.             if you ignore the man page overwrite warning dialog.
  2160.  
  2161.             To avoid losing your changes to a manpage file
  2162.             generated by C++ Browser do the following:
  2163.  
  2164.             *    Move the existing manpage out of the way to some
  2165.                  other file.
  2166.  
  2167.             *    Generate the new (skeleton) man page.
  2168.  
  2169.             *    Merge the changes from the saved file to the new
  2170.                  man page generated by the C++ Browser.
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.                                   - 34 -
  2183.  
  2184.  
  2185.  
  2186.           +o When you use an application which allocates lot of
  2187.             colors in the default color map and then use cvstatic
  2188.             or C++ browser to bring up graphs, you might get all
  2189.             black nodes with un-readable text. The only known
  2190.             workaround to this problem is to kill the X server and
  2191.             login again. Be sure that you bring up cvstatic before
  2192.             you bring up the offending application. This problem
  2193.             has been seen with viewing books which have full color
  2194.             pictures.
  2195.  
  2196.  
  2197.        5.7  _W_o_r_k_S_h_o_p__P_e_r_f_o_r_m_a_n_c_e__A_n_a_l_y_z_e_r
  2198.  
  2199.           +o On some systems with 16K or larger pages size, some
  2200.             versions of libXm.so.1 when instrumented for PC
  2201.             sampling, can not be loaded.  Try using SpeedShop's PC
  2202.             sampling instead (Incident #515045).
  2203.  
  2204.           +o On some systems, libgl.so will crash when instrumented
  2205.             for PC sampling.  Try using SpeedShop's PC sampling
  2206.             instead (Incident #515048).
  2207.  
  2208.           +o _c_v_p_c_s may core dump when profiling Ada applications
  2209.             (Incident #478331).
  2210.  
  2211.           +o Instrumentation may generate an incorrect file name for
  2212.             instantiated templates from C++ (Incident #284412).
  2213.  
  2214.           +o Ideal-time and CPU-time experiments on programs that do
  2215.             dlopen's may fail on R5K Indy machines, due to a HW bug
  2216.             that causes traps to be missed the first time through.
  2217.             The recording of performance experiments relies on an
  2218.             internal trap to dlopen in order to instrument the DSO
  2219.             being dlopen'd (Incident #439770).
  2220.  
  2221.           +o Total-time and bottleneck experiments will overcount
  2222.             inclusive time for recursive functions (Incident
  2223.             #438591)
  2224.  
  2225.           +o Running the Bottleneck and Total-Time experiments
  2226.             significantly slow the execution of some programs
  2227.             because of the time it takes to unwind the stack.
  2228.  
  2229.           +o _c_v_p_e_r_f is not backwards-compatible with experiments
  2230.             recorded on prior WorkShop releases, and will typically
  2231.             core dump on them.
  2232.  
  2233.           +o Instrumenting _l_i_b_c with the PC-sampling option will
  2234.             fail in IRIX 5.3 because there is not enough address
  2235.             space left for text and data sections (Incident
  2236.             #223912).  These experiments work in IRIX 6.2 or later.
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.                                   - 35 -
  2249.  
  2250.  
  2251.  
  2252.             Workaround:  There is no workaround for this problem on
  2253.             IRIX 5.3.
  2254.  
  2255.           +o Memory leak experiments on programs that fork may
  2256.             produce misleading data.  For example, a child process
  2257.             may free a block allocated in the parent, which will
  2258.             appear as a bad free.  (Incident #202710)
  2259.  
  2260.           +o During data collection, the collector, _c_v_m_o_n, might run
  2261.             out of disk space.  In this case, it posts an error
  2262.             pop-up to the effect of ``bead write failed: no space
  2263.             left on device''.
  2264.  
  2265.             Workaround: Exit the debugger, free up sufficient space
  2266.             on the disk, and start the run again.
  2267.  
  2268.           +o The Performance Analyzer does not support COFF
  2269.             executables.
  2270.  
  2271.           +o The Performance tools can collect a great deal of data,
  2272.             and easily fill a disk.  For typical programs, basic-
  2273.             block sampling can collect between 0.25 and 2 Mbytes of
  2274.             data at each sample point.  PC sampling data can amount
  2275.             to between 0.25 and 6 Mbytes for each sample.
  2276.  
  2277.             Workaround: Use care in specifying how many samples you
  2278.             take to avoid this problem.  Be especially careful in
  2279.             using Pollpoint sampling; it should normally be used
  2280.             collecting only callstacks, not function counts,
  2281.             basic-block counts, or PC sampling data.  Sampling is
  2282.             not expensive in tracing experiments.
  2283.  
  2284.           +o The Main View has a notion of a default trap that is a
  2285.             stop trap if data collection has not been enabled in
  2286.             the Performance Panel (where ``enabled'' means after
  2287.             _A_c_c_e_p_t or _O_K was clicked), and a sample trap if it has
  2288.             been enabled.  This setting is independent of the
  2289.             default trap set in the Trap Manager.  Clicking in the
  2290.             margin of the MainView source window sets or clears the
  2291.             MainView default trap, and does not affect a trap of
  2292.             the other type.
  2293.  
  2294.           +o _m_a_l_l_o_c/_f_r_e_e traces can be quite voluminous and
  2295.             difficult to process in Heap View.  When doing
  2296.             _m_a_l_l_o_c/_f_r_e_e tracing, be careful to design your
  2297.             experiments to exercise only those regions of your code
  2298.             that are problematic, and minimize the amount of trace
  2299.             data collected.  It is difficult to estimate the volume
  2300.             of data produced.  Each event writes 20 to 80 bytes, or
  2301.             more, depending on the depth of the callstack at the
  2302.             time of the call. A 10-minute experiment with the
  2303.  
  2304.  
  2305.  
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.                                   - 36 -
  2315.  
  2316.  
  2317.  
  2318.             WorkShop Performance Analyzer wrote 140 Mbytes of trace
  2319.             data.  Reading this experiment took ~12 minutes on a
  2320.             256-MB Onyx machine.
  2321.  
  2322.           +o The WorkShop Performance Analyzer can record
  2323.             experiments on MP FORTRAN programs, but there are a
  2324.             number of anomalies in the displayed data that require
  2325.             explanation.  For all FORTRAN MP compilations, parallel
  2326.             loops within the program are represented as subroutines
  2327.             with names relating to the source routine in which they
  2328.             are embedded.  The naming conventions for these
  2329.             subroutines are different for o32-bit, N32, and 64-bit
  2330.             compilations.  In the linpack benchmark, most of the
  2331.             time spent is in the source routine _D_A_X_P_Y, which can be
  2332.             parallelized.  The MP loop-body routines are invoked
  2333.             indirectly from the original function, and will show up
  2334.             as directly calls from a routine name __mp_parallel_do.
  2335.  
  2336.             When compiled with the 7.2 compilers, in either 64-
  2337.             bits, or n32, the MP loop-body routine is named
  2338.             "__mpdo_daxpy_1", and the function is named "daxpy_".
  2339.             However, there is a test in the compiled loop to
  2340.             determine if the work to be done is sufficient to be
  2341.             worth running in parallel.  That means if the test
  2342.             succeeds, time will be shown in the routine
  2343.             __mpdo_daxpy_1, while if the test fails, the time will
  2344.             be recorded in the routine daxpy_.
  2345.  
  2346.             In an o32-bit version, the _D_A_X_P_Y routine is named
  2347.             "daxpy_", and the MP loop body routine
  2348.             "_daxpy_519_aaab_".
  2349.  
  2350.             In all three cases, for an ideal time experiment on a
  2351.             uniprocessor -_g run, the inclusive and exclusive
  2352.             function level times are correct.  The source
  2353.             annotations, however, behave differently and
  2354.             incorrectly in most cases.
  2355.  
  2356.             With the 7.2 or 6.x compilers, source annotations for
  2357.             the exclusive time are correctly shown for each line,
  2358.             but the inclusive time for the first line of the loop
  2359.             (_d_o statement) includes the time spent in the loop
  2360.             body. This same time appears on the lines comprising
  2361.             the loop's body, in effect, representing a double-
  2362.             counting.  When used in conjunction with WorkShop Pro
  2363.             MPF's Parallel Analyzer View, the loop performance data
  2364.             will incorrectly also reflect the double counting, and
  2365.             the time will not be always shown as a percentage:
  2366.             whenever it would exceed 100%, it is shown as <_n/_a>.
  2367.             The numerical time value shown reflects the double
  2368.             counting.
  2369.  
  2370.  
  2371.  
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.                                   - 37 -
  2381.  
  2382.  
  2383.  
  2384.             In 32-bit source annotations, the exclusive time is
  2385.             incorrectly shown for the line comprising the loop's
  2386.             body, as the line-level data for the loop-body routine
  2387.             ("_daxpy_519_aaab_") does not refer to proper lines.
  2388.             If the program was compiled with the -_m_p__k_e_e_p flag, the
  2389.             line-level data should refer to the temporary files
  2390.             that are saved from the compilation, but the temporary
  2391.             files do not contain that information, so no source or
  2392.             disassembly data can be shown.  The disassembly data
  2393.             for the main routine does not show the times for the
  2394.             loop-body.
  2395.  
  2396.             If the 32-bit program was compiled without -_m_p__k_e_e_p,
  2397.             the line-level data for the loop-body routine is
  2398.             incorrect, with most lines referred to line 0 of the
  2399.             file, and the rest to other lines at seemingly random
  2400.             places in the file.  Consequently, spurious annotations
  2401.             will appear on these other lines.  Disassembly
  2402.             correctly shows the instructions, and their data, but
  2403.             the line numbers shown are wrong.  MPF's Parallel
  2404.             Analyzer correctly shows the loop data in most cases,
  2405.             but the same incorrect line numbers can cause data
  2406.             relating to one loop to show up in other parts of the
  2407.             program.  This reflects what is essentially the same
  2408.             double-counting problem as seen in 64-bits, but the
  2409.             extra counts go to other places in the file, rather
  2410.             than the first line of the loop.
  2411.  
  2412.             NNNNOOOOTTTTEEEE:::: We recommend against using the -_m_p__k_e_e_p flag.
  2413.  
  2414.           +o For MP experiments, switching between threads will
  2415.             cause the calipers to change to points valid for the
  2416.             new thread. Switching back may use different points,
  2417.             and therefore, show different numbers. Set the calipers
  2418.             manually after switching to ensure proper placement.
  2419.  
  2420.           +o For MP experiments, stopping one thread can cause the
  2421.             notion of time in other threads to get confused.  It is
  2422.             not recommended.
  2423.  
  2424.           +o The inclusive data shown in _c_v_p_e_r_f represents the
  2425.             instruction counts and/or PC sampling data summed over
  2426.             the routine and those routines that it calls.  The
  2427.             computations are based on a heuristic that assumes that
  2428.             all calls from all callers are equivalent.  For
  2429.             programs where this heuristic is not applicable, for
  2430.             example, where one call to a matrix-multiply routine is
  2431.             for matrices of order four, while a second call is for
  2432.             matrices of order 100, the cumulative data may be
  2433.             misleading.
  2434.  
  2435.  
  2436.  
  2437.  
  2438.  
  2439.  
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.                                   - 38 -
  2447.  
  2448.  
  2449.  
  2450.           +o Line-level data assigns a value to a line equal to the
  2451.             highest value for any instructions attributed to that
  2452.             line.  It can be confusing, because compiler
  2453.             optimizations often rearrange the code in ways that is
  2454.             non-obvious.  Looking at a disassembly view of the data
  2455.             can help.
  2456.  
  2457.           +o Line-level data from assembler routines can be
  2458.             misleading.  The symbol table often has instructions
  2459.             attributed to the wrong source line.
  2460.  
  2461.           +o In some cases, line number data for a C++ routine that
  2462.             uses inline virtual functions defined in an included
  2463.             file gets the line numbers incorrectly displayed as if
  2464.             they came from the file in which the defining file is
  2465.             included.  This causes incorrect line-level data to
  2466.             show at the lines in the original file.  The
  2467.             Disassembly View in _c_v_p_e_r_f shows performance data for
  2468.             each instruction, and may help disambiguate attribution
  2469.             (Incident #433284).
  2470.  
  2471.           +o _c_v_p_e_r_f filters out nodes and arcs that were not
  2472.             executed during the current caliper setting.  This
  2473.             feature can lead to confusing displays, where nodes
  2474.             that are known to be in the program do not appear.
  2475.  
  2476.             Workaround: The Preferences menu can be used to disable
  2477.             the filtering.
  2478.  
  2479.           +o _c_v_p_e_r_f does not support live performance experiments.
  2480.             That is, you should not bring up _c_v_p_e_r_f until the
  2481.             experiment is over.  If you do, it will not update as
  2482.             more data is recorded.
  2483.  
  2484.           +o Performance experiments on multi-process applications
  2485.             can occasionally be unreliable if sample events are
  2486.             quickly preceded by process creation, or succeeded by
  2487.             process termination.
  2488.  
  2489.           +o Heap View scrolls poorly and blocks flash on large
  2490.             experiments.  Its functionality has been mostly
  2491.             subsumed by Leak View, Malloc View, and Malloc Error
  2492.             View.  (Incident# 67628)
  2493.  
  2494.           +o Callstacks may be wrong in MP experiments.  (Incident#
  2495.             189826)
  2496.  
  2497.           +o Pollpoint sampling will fail if the target process
  2498.             forks, and the parent exits before the child.
  2499.             (Incident #186429)
  2500.  
  2501.  
  2502.  
  2503.  
  2504.  
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.                                   - 39 -
  2513.  
  2514.  
  2515.  
  2516.           +o The Performance Analyzer can dump core when computing
  2517.             line-level annotations on o32 programs.
  2518.  
  2519.             Workaround: Exit _c_v_d and call _c_v_p_e_r_f directly.
  2520.  
  2521.  
  2522.        5.8  _W_o_r_k_S_h_o_p__T_e_s_t_e_r
  2523.  
  2524.        5.8.1  _W_o_r_k_S_h_o_p__T_e_s_t_e_r__L_i_m_i_t_a_t_i_o_n_s
  2525.  
  2526.           +o Instrumented programs can increase in size by a factor
  2527.             of 2X to 5X.  However, DSO caching and sharing
  2528.             alleviates this problem greatly.
  2529.  
  2530.           +o Block and branch coverage are at the assembly language
  2531.             level.  They can provide useful metrics and do map back
  2532.             to the source lines.  Note that several assembly branch
  2533.             instructions may map back to the same source line.  To
  2534.             see the C, C++, and Fortran source level blocks and
  2535.             branches, use _c_v_c_o_v _l_s_s_o_u_r_c_e.
  2536.  
  2537.           +o Compilation with the debug flag -_g builds assembly
  2538.             language branches and blocks that can never be
  2539.             executed.  This adversely affects overall coverage.  By
  2540.             compiling with "O1" (the default), some of the unused
  2541.             assembly branches and blocks are not built.  This gives
  2542.             a more accurate block and branch coverage metric.
  2543.             Function and arc coverage are unaffected by compile
  2544.             flags.
  2545.  
  2546.           +o C++ in-line functions are not counted as functions
  2547.             unless they are out-of-lined by the compiler.
  2548.  
  2549.           +o By default, arguments of functions are not displayed in
  2550.             query results.  This can be confusing for C++
  2551.             overloaded functions because there is no way to
  2552.             distinguish between them.  To work around this problem,
  2553.             use the -_a_r_g option to show full function signatures.
  2554.  
  2555.           +o The default size of the SourceView annotation canvas
  2556.             may not be large enough to hold very large counts.  The
  2557.             resource name for setting canvas width for SourceView
  2558.             is "canvasWidth".  The default value is 60.  The user
  2559.             can modify this width by modifying the following
  2560.             resource found in the Cvxcov app-defaults file,
  2561.             "Cvxcov*test*testData*canvasWidth".
  2562.  
  2563.           +o _T_e_s_t_e_r currently uses object level instrumentation.
  2564.             This has several advantages:
  2565.  
  2566.                 ((((1111)))) CCCCoooovvvveeeerrrraaaaggggeeee ddddaaaattttaaaa ccccaaaannnn bbbbeeee oooobbbbttttaaaaiiiinnnneeeedddd wwwwiiiitttthhhhoooouuuutttt aaaacccccccceeeessssssss ttttoooo tttthhhheeee
  2567.  
  2568.  
  2569.  
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.                                   - 40 -
  2579.  
  2580.  
  2581.  
  2582.                     ssssoooouuuurrrrcccceeee ccccooooddddeeee....
  2583.                 ((((2222)))) CCCCoooovvvveeeerrrraaaaggggeeee ddddaaaattttaaaa ccccaaaannnn bbbbeeee oooobbbbttttaaaaiiiinnnneeeedddd wwwwiiiitttthhhhoooouuuutttt rrrreeeeccccoooommmmppppiiiillllaaaattttiiiioooonnnn////rrrreeeebbbbuuuuiiiilllldddd....
  2584.                 ((((3333)))) TTTThhhhiiiissss ssssuuuuppppppppoooorrrrttttssss CCCC,,,, CCCC++++++++,,,, aaaannnndddd FFFFoooorrrrttttrrrraaaannnn wwwwiiiitttthhhhoooouuuutttt ssssppppeeeecccciiiiaaaallll
  2585.                     llllaaaannnngggguuuuaaaaggggeeee ssssuuuuppppppppoooorrrrtttt ffffrrrroooommmm tttthhhheeee ccccoooommmmppppiiiilllleeeerrrrssss....
  2586.  
  2587.             This has several disadvantages:
  2588.  
  2589.                 ((((1111)))) BBBBlllloooocccckkkk aaaannnndddd bbbbrrrraaaannnncccchhhh ccccoooouuuunnnnttttssss aaaarrrreeee aaaatttt tttthhhheeee aaaasssssssseeeemmmmbbbbllllyyyy llllaaaannnngggguuuuaaaaggggeeee lllleeeevvvveeeellll....
  2590.                 ((((2222)))) MMMMoooorrrreeee ddddeeeettttaaaaiiiilllleeeedddd ccccoooovvvveeeerrrraaaaggggeeee rrrreeeeqqqquuuuiiiirrrreeeessss kkkknnnnoooowwwwlllleeeeddddggggeeee ooooffff tttthhhheeee
  2591.                     llllaaaannnngggguuuuaaaaggggeeee sssseeeemmmmaaaannnnttttiiiiccccssss.... FFFFoooorrrr eeeexxxxaaaammmmpppplllleeee,,,, hhhhaaaassss eeeevvvveeeerrrryyyy ppppoooossssssssiiiibbbblllleeee ccccaaaasssseeee
  2592.                     iiiinnnn aaaa mmmmuuuullllttttiiiipppplllleeee ccccoooonnnnddddiiiittttiiiioooonnnnaaaallll ffffiiiirrrreeeedddd dddduuuurrrriiiinnnngggg tttteeeessssttttiiiinnnngggg....
  2593.  
  2594.           +o _W_e_a_k _e_x_t_e_r_n_a_l_s refer to an aliasing facility used by
  2595.             the compilation environment.  For example, while user
  2596.             programs may call the function "read", the actual
  2597.             function name in the C library that implements "read"
  2598.             is "_read". In this case, "read" is a weak external for
  2599.             "_read".  If the user CONSTRAINS coverage on either
  2600.             name, _T_e_s_t_e_r will report the results correctly.
  2601.             However, _T_e_s_t_e_r will choose the name used to implement
  2602.             the function, in this case "_read".
  2603.  
  2604.           +o -_f_u_n_c__p_a_t_t_e_r_n is a function pattern used in the
  2605.             following _c_v_c_o_v subcommands: _l_s_b_l_o_c_k, _l_s_b_r_a_n_c_h, _l_s_f_u_n,
  2606.             _l_s_t_r_a_c_e.  Currently, only the following "patterns" are
  2607.             matched.
  2608.  
  2609.                 """"DDDDSSSSOOOO::::****""""              -------- aaaallllllll ffffuuuunnnnccccttttiiiioooonnnnssss iiiinnnn aaaa DDDDSSSSOOOO
  2610.                 DDDDSSSSOOOO::::ffffuuuunnnnccccttttiiiioooonnnn____nnnnaaaammmmeeee    -------- ssssppppeeeecccciiiiffffiiiicccc ffffuuuunnnnccccttttiiiioooonnnn iiiinnnn aaaa DDDDSSSSOOOO
  2611.                 ffffuuuunnnnccccttttiiiioooonnnn____nnnnaaaammmmeeee        -------- ffffuuuunnnnccccttttiiiioooonnnn____nnnnaaaammmmeeee iiiinnnn mmmmaaaaiiiinnnn pppprrrrooooggggrrrraaaammmm aaaannnndddd ddddssssoooo''''ssss
  2612.                 <<<< ooooppppttttiiiioooonnnn nnnnooootttt uuuusssseeeedddd >>>>  -------- aaaallllllll ffffuuuunnnnccccttttiiiioooonnnnssss aaaarrrreeee iiiinnnncccclllluuuuddddeeeedddd iiiinnnn qqqquuuueeeerrrryyyy
  2613.  
  2614.           +o Sharing of the WorkShop Performance Analyzer
  2615.             performance experiment data is supported in _c_v_c_o_v but
  2616.             not in _c_v_x_c_o_v of this release.
  2617.  
  2618.           +o Output of query results to a printer is not supported
  2619.             in this release.  As a workaround, the user can save
  2620.             query results to a file, and then send that file to a
  2621.             printer.
  2622.  
  2623.           +o Experiment data for test sets/test groups cannot be
  2624.             moved/copied (mv, cp) without invalidating the data.
  2625.             Leaf tests can be moved/copied.
  2626.  
  2627.           +o Both the _l_s_t_r_a_c_e feature (argument tracing) and the
  2628.             _l_s_s_o_u_r_c_e feature (mapping block counts to actual
  2629.             source) require the code to be compiled with -_g.  A
  2630.             notable exception to this is return value tracing which
  2631.             can trace the return value on functions that are not
  2632.             compiled with -_g (e.g., _l_i_b_c functions).
  2633.  
  2634.  
  2635.  
  2636.  
  2637.  
  2638.  
  2639.  
  2640.  
  2641.  
  2642.  
  2643.  
  2644.                                   - 41 -
  2645.  
  2646.  
  2647.  
  2648.           +o _c_v_c_o_v requires that all instrumentation be performed
  2649.             before the experiment is run. This includes
  2650.             instrumentation for programs that are forked/exec'ed or
  2651.             sproc'ed.  _c_v_m_o_n is the program used by _c_v_c_o_v to
  2652.             monitor the experiment.  If _c_v_m_o_n encounters child
  2653.             processes, and the coverage experiment includes any
  2654.             executables other than the main program, then _c_v_m_o_n
  2655.             will instrument the executables for the child processes
  2656.             "on the fly".  _c_v_c_o_v will not process coverage for
  2657.             these "on the fly" instrumented executables, because
  2658.             _c_v_m_o_n has not used the correct coverage instrumentation
  2659.             criteria.  This can cause performance and space
  2660.             overhead.
  2661.  
  2662.           +o IRIX 5.1 and later binaries are supported (no support
  2663.             for IRIX 4.0.X binaries) including shared and
  2664.             nonshared.
  2665.  
  2666.           +o Instrumentation criteria ccccoooouuuunnnnttttssss must at least include
  2667.             ----bbbbbbbbccccoooouuuunnnntttt.  For example, if user want to test function
  2668.             pointers the instrumentation file must contain the
  2669.             following line,
  2670.  
  2671.                 CCCCOOOOUUUUNNNNTTTTSSSS ----bbbbbbbbccccoooouuuunnnnttttssss ----ffffppppccccoooouuuunnnnttttssss
  2672.  
  2673.           +o The current model for running instrumented programs
  2674.             requires that a separate process (_c_v_m_o_n) monitor the
  2675.             programs that are undergoing coverage analysis.  This
  2676.             requires existing test scripts to be modified in the
  2677.             following manner:
  2678.  
  2679.                 oooolllldddd ssssccccrrrriiiipppptttt::::
  2680.                    #### pppprrrrooooggggrrrraaaammmm aaaarrrrgggg1111 aaaarrrrgggg2222
  2681.                 nnnneeeewwww ssssccccrrrriiiipppptttt::::
  2682.                    #### ccccvvvvccccoooovvvv mmmmkkkktttteeeesssstttt ----ccccmmmmdddd """"pppprrrrooooggggrrrraaaammmm aaaarrrrgggg1111 aaaarrrrgggg2222"""" ----tttteeeessssttttnnnnaaaammmmeeee tttteeeesssstttt
  2683.                    #### ccccvvvvccccoooovvvv rrrruuuunnnntttteeeesssstttt tttteeeesssstttt
  2684.  
  2685.           +o There is potentially a large amount of data that can be
  2686.             captured when running multiple tests for large
  2687.             programs.  There are several options to the _r_u_n_t_e_s_t
  2688.             command that help manage this data.
  2689.  
  2690.             The -_n_o_a_r_c option is used to eliminate the capture of
  2691.             arc data in the experiment result (e.g., arc AB is
  2692.             equivalent to function A calls function B from line X).
  2693.             This significantly reduces the amount of overall count
  2694.             information for the test coverage result.
  2695.  
  2696.             The -_r_m_s_u_b option is used to retain the overall results
  2697.             for the top level test set or test group, not for the
  2698.             individual subtests.  There are several interactions of
  2699.  
  2700.  
  2701.  
  2702.  
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.                                   - 42 -
  2711.  
  2712.  
  2713.  
  2714.             the -_r_m_s_u_b and -_s_u_m options worth noting.  If the
  2715.             -_r_m_s_u_b option is used, a subsequent "runtest" using the
  2716.             -_s_u_m option will not accumulate the counts data for
  2717.             these two runs.  In this case only the second run will
  2718.             be in the top level test set/test group.  The -_s_u_m
  2719.             option will sum up data only according to the count
  2720.             data that is in all the subtests currently and does not
  2721.             use the information in the top level test set or test
  2722.             group.  When using the -_s_u_m and -_r_m_s_u_b options
  2723.             together, the count data will be accumulated and the
  2724.             subtest data will be deleted.
  2725.  
  2726.             The -_c_o_m_p_r_e_s_s option is used to compress experiment
  2727.             database using standard utility _c_o_m_p_r_e_s_s.
  2728.  
  2729.             The -_b_i_t_c_o_u_n_t option is used to convert experiment
  2730.             database to 1-bit-per-count format in recording
  2731.             experiment so that it will save disk space up to 32
  2732.             times. However, count number for basic blocks and
  2733.             branch coverage information will be lost.
  2734.  
  2735.           +o Source highlighting for statement that cover multiple
  2736.             lines only highlights the last line. This is due to a
  2737.             limitation in symbol table data generated by the
  2738.             compiler.  For example, in the following source
  2739.             statement only the second line will be highlighted:
  2740.  
  2741.                     pppprrrriiiinnnnttttffff((((""""TTTThhhhiiiissss iiiissss aaaa tttteeeesssstttt ffffoooorrrr %%%%ssss aaaatttt %%%%dddd"""",,,,
  2742.             0000            tttteeeessssttttnnnnaaaammmmeeee,,,,wwwwhhhhiiiicccchhhhDDDDrrrriiiivvvveeee))));;;;
  2743.  
  2744.           +o If the DSO cache directory has been removed, all the
  2745.             existing experiments may be invalid and _T_e_s_t_e_r may not
  2746.             work.
  2747.  
  2748.        5.8.2  _W_o_r_k_S_h_o_p__T_e_s_t_e_r__B_u_g_s
  2749.  
  2750.           +o Programs that use _a_r_g_v[_0] to build hardcoded filenames
  2751.             get confused by the renamed instrumented program (e.g.,
  2752.             <program> becomes <program_Instr>).
  2753.  
  2754.  
  2755.        5.9  _W_o_r_k_S_h_o_p__E_n_v_i_r_o_n_m_e_n_t
  2756.  
  2757.           +o If the colors of your WorkShop windows look too dark to
  2758.             read or conversely if they look completely washed out,
  2759.             there may be a discrepancy between the gamma value you
  2760.             are using and the value your X server is using.  The
  2761.             default value of gamma on installation is 1.7 but users
  2762.             running X programs may prefer a value of 1.0.
  2763.  
  2764.  
  2765.  
  2766.  
  2767.  
  2768.  
  2769.  
  2770.  
  2771.  
  2772.  
  2773.  
  2774.  
  2775.  
  2776.                                   - 43 -
  2777.  
  2778.  
  2779.  
  2780.             Workaround: If you change your gamma value, by running
  2781.             the _g_a_m_m_a program (installed with _e_o_e_2._s_w._g_l_t_o_o_l_s),
  2782.             restart your X server.
  2783.  
  2784.           +o When starting up WorkShop, if you see the messages
  2785.  
  2786.             ////uuuussssrrrr////ssssbbbbiiiinnnn////ttttttttsssseeeessssssssiiiioooonnnn:::: CCCCaaaannnn''''tttt iiiinnnniiiitttt ttttyyyyppppeeee ddddaaaattttaaaabbbbaaaasssseeee....
  2787.             ////uuuussssrrrr////ssssbbbbiiiinnnn////ttttttttsssseeeessssssssiiiioooonnnn:::: eeeexxxxiiiittttiiiinnnngggg
  2788.             WWWWaaaarrrrnnnniiiinnnngggg:::: ttttttttsssseeeessssssssiiiioooonnnn:::: ssssiiiigggg____hhhhaaaannnnddddlllleeeerrrr:::: NNNNoooo cccchhhhiiiilllldddd pppprrrroooocccceeeesssssssseeeessss
  2789.             ////uuuussssrrrr////ssssbbbbiiiinnnn////ttttttttsssseeeessssssssiiiioooonnnn:::: CCCCaaaannnn''''tttt iiiinnnniiiitttt sssseeeerrrrvvvveeeerrrr....
  2790.             ttttttttsssseeeessssssssiiiioooonnnn:::: CCCCaaaannnn''''tttt iiiinnnniiiitttt ttttyyyyppppeeee ddddaaaattttaaaabbbbaaaasssseeee....
  2791.             ttttttttsssseeeessssssssiiiioooonnnn:::: eeeexxxxiiiittttiiiinnnngggg
  2792.             WWWWaaaarrrrnnnniiiinnnngggg:::: ttttttttsssseeeessssssssiiiioooonnnn:::: ssssiiiigggg____hhhhaaaannnnddddlllleeeerrrr:::: NNNNoooo cccchhhhiiiilllldddd pppprrrroooocccceeeesssssssseeeessss
  2793.             ttttttttsssseeeessssssssiiiioooonnnn:::: CCCCaaaannnn''''tttt iiiinnnniiiitttt sssseeeerrrrvvvveeeerrrr....
  2794.             TTTTttttuuuuttttiiiillll:::: CCCCaaaannnnnnnnooootttt ooooppppeeeennnn oooouuuurrrr TTTToooooooollllTTTTaaaallllkkkk pppprrrroooocccceeeessssssss iiiidddd
  2795.             ttttttttuuuuttttiiiillll:::: CCCCoooouuuullllddddnnnn''''tttt ccccoooonnnnnnnneeeecccctttt ttttoooo ttttttttsssseeeessssssssiiiioooonnnn sssseeeerrrrvvvviiiicccceeee((((ssss))))....
  2796.  
  2797.             check if you have the _C_E_P_A_T_H environment variable set.
  2798.             ToolTalk will use the _C_E_P_A_T_H variable for its
  2799.             definition of where the types database are located.
  2800.             WorkShop expects to find them in the default system
  2801.             database, /_e_t_c/_t_t/_t_y_p_e_s._x_d_r. Unsetting this environment
  2802.             variable will fix the startup problem.
  2803.  
  2804.           +o When starting up WorkShop, you may occassionally see
  2805.             the message
  2806.  
  2807.             ////uuuussssrrrr////ssssbbbbiiiinnnn////ttttttttsssseeeessssssssiiiioooonnnn:::: WWWWaaaarrrrnnnniiiinnnngggg:::: ccccoooouuuullllddddnnnn''''tttt aaaaccccqqqquuuuiiiirrrreeee XXXX sssseeeelllleeeeccccttttiiiioooonnnn
  2808.  
  2809.             ToolTalk displays this message when its internal state
  2810.             notes that someone else (i.e. another _t_t_s_e_s_s_i_o_n) has
  2811.             already owned the X selection that it is trying to
  2812.             aquire.  This message is harmless and can be ignored.
  2813.  
  2814.           +o The network license mechanism used by WorkShop performs
  2815.             periodic checks to ensure that a license is available.
  2816.             Once obtained, a license is valid for 20 minutes. The
  2817.             license is validated every 10 minutes, and renewed for
  2818.             an additional 20 minutes if all is well. This process
  2819.             requires that WorkShop be actively running to be able
  2820.             to perform these checks. If the tool is unable to check
  2821.             the license server for 20 minutes, the license is lost,
  2822.             and the tool must be restarted to get a new license.
  2823.             Therefore, suspending a WorkShop process (using <Ctrl-
  2824.             Z>, for example) for more than a few minutes loses the
  2825.             tool's license.
  2826.  
  2827.           +o The WorkShop environment works with one configuration
  2828.             management system at a time. This affects all users
  2829.             running WorkShop on that machine.
  2830.  
  2831.  
  2832.  
  2833.  
  2834.  
  2835.  
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.                                   - 44 -
  2843.  
  2844.  
  2845.  
  2846.           +o The default for string data is to display it as a hex
  2847.             address.  If you prefer the behavior of showing a
  2848.             string for _c_h_a_r *, you can set ****aaaauuuuttttooooSSSSttttrrrriiiinnnnggggFFFFoooorrrrmmmmaaaatttt to
  2849.             TTTTrrrruuuueeee in your ._X_d_e_f_a_u_l_t_s.  This will automatically
  2850.             change the result format from the default to string for
  2851.             _c_h_a_r * and _c_h_a_r <_a_r_r_a_y> expressions in the
  2852.             ExpressionView, VarBrowser, and DataBrowser.
  2853.  
  2854.           +o Customers displaying to non-SGI X displays and having
  2855.             difficulties with ExecutionView startup (a busy cursor
  2856.             that never goes away) should try switching
  2857.             ****eeeexxxxeeeeccccuuuuttttiiiioooonnnnVVVViiiieeeewwww****TTTTeeeerrrrmmmmiiiinnnnaaaallllCCCCoooommmmmmmmaaaannnndddd in
  2858.             /_u_s_r/_W_o_r_k_S_h_o_p/_u_s_r/_l_i_b/_X_1_1/_a_p_p-_d_e_f_a_u_l_t_s/_C_v_m_a_i_n from the
  2859.             _x_w_s_h version to the commented out _x_t_e_r_m version.
  2860.  
  2861.  
  2862.  
  2863.  
  2864.  
  2865.  
  2866.  
  2867.  
  2868.  
  2869.  
  2870.  
  2871.  
  2872.  
  2873.  
  2874.  
  2875.  
  2876.  
  2877.  
  2878.  
  2879.  
  2880.  
  2881.  
  2882.  
  2883.  
  2884.  
  2885.  
  2886.  
  2887.  
  2888.  
  2889.  
  2890.  
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899.  
  2900.  
  2901.  
  2902.  
  2903.  
  2904.  
  2905.